{"openapi":"3.1.0","info":{"title":"Lahjty API","version":"2026-09-12","summary":"Arabic and English campaign generation for business software.","description":"Generate Arabic or English marketing copy, durable images, Arabic and English speech, complete campaigns, and Meta-shaped WhatsApp template drafts. All POST operations require an Idempotency-Key. Failed billable attempts are reconciled automatically; inspect refund_pending and credits_refunded before treating the credit outcome as final. Partner-reported Meta outcomes are recorded for measurement; an unchanged rejected template becomes a refund candidate and is refunded exactly once only after Lahjty verifies trusted Meta or provider evidence.","contact":{"name":"Lahjty","url":"https://www.lahjty.com/en/api-docs"},"license":{"name":"Proprietary","url":"https://www.lahjty.com/en/terms-of-service"}},"servers":[{"url":"https://www.lahjty.com/api/v1","description":"Production"}],"tags":[{"name":"Discovery","description":"Public API capabilities and current cost metadata."},{"name":"Generation","description":"Billable localized copy, image, speech, and campaign creation."},{"name":"Templates","description":"WhatsApp template drafting and partner-reported Meta outcomes."},{"name":"Operations","description":"Authenticated balance, usage, and request-status inspection."}],"paths":{"/ad-library":{"get":{"operationId":"searchAdLibrary","summary":"Search ads or rank catalog matches for a brief","description":"Requires ad-library:read. Prefer brief for natural requests: matches catalog metadata without requiring every city or request word. q first uses all-word matching, then falls back to labeled related metadata matches within the same explicit filters. No measured performance claims. An exact id (or ad ID in q) returns only that ad or 404. Invalid industry/sector/style values return 422; use the enumerated values or omit the filter.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"id","schema":{"type":"string","maxLength":100}},{"in":"query","name":"q","schema":{"type":"string","maxLength":200}},{"in":"query","name":"brief","schema":{"type":"string","maxLength":2000}},{"in":"query","name":"locale","schema":{"type":"string","enum":["en","ar"]}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":30,"default":10}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"maximum":10000}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"maximum":99}},{"in":"query","name":"industry","schema":{"type":"string","enum":["SaaS & Cloud Software","AI Tools","E-commerce & Physical Products","Mobile Apps & Games","Finance & FinTech","Health, Fitness & Wellness","Beauty & Skincare","Food & Beverage","Info-Products & Courses","Professional B2B Services","Local & Home Services","Travel & Hospitality","Automotive","Other / General"]}},{"in":"query","name":"sector","schema":{"type":"string","enum":["all","saas","ai","ecommerce","apps","fintech","health","beauty","food","education","b2b","local","travel","automotive","general"]}},{"in":"query","name":"style","schema":{"type":"string","enum":["all","product","offer","launch","proof","problem","comparison","educational","story","hook"]}}],"responses":{"200":{"description":"Catalog items with match rationale and next page/offset","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/{id}":{"get":{"operationId":"getAdLibraryItem","summary":"Inspect an ad, editable fields, reference requirements and preparation state","description":"Requires ad-library:read. Read-only, no analysis or generation charge.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"schema":{"default":"en","enum":["en","ar"],"type":"string"},"name":"locale","in":"query"}],"responses":{"200":{"description":"Ad and available generation contract","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/{id}/prepare":{"post":{"operationId":"prepareAdLibraryItem","summary":"Explicitly prepare an ad's editable contract","description":"Requires ad-library:write. Missing analysis costs one credit; an already prepared contract costs zero. The shared analysis ledger owns debit and refund recovery. usage.credits_used reports this analysis charge; balance_after is null. Read detail after a pending/uncertain result. Reuse the exact body and Idempotency-Key on retry. Pending 409 and allowance 429 are retryable with that same key; wait for completion or the stated reset time. Each failed attempt remains inspectable.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"locale":{"type":"string","enum":["en","ar"],"default":"en"}}},"examples":{"prepare":{"value":{"locale":"ar"}}}}}},"responses":{"200":{"description":"Prepared contract and actual analysis charge","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/{id}/generations":{"post":{"operationId":"generateAdLibraryImage","summary":"Generate a saved ad from approved editable fields and owned images","description":"Requires images:write. Charges the image credit cost. Saves the image in History. With logo_mode overlay, also preserves the clean original and editable logo composition; model-rendered branding is part of the artwork. A supplied logo defaults to model mode; none ignores it. Preparation is explicit and never runs automatically. Saved snippet and terminal request complete atomically.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdLibraryGenerationRequest"},"examples":{"arabic":{"value":{"reference_storage_ids":["owned_storage_id"],"template_fields":{"headline":"قهوة مختصة","cta":"اطلب الآن"},"aspect_ratio":"1:1","locale":"ar"}}}}}},"responses":{"201":{"description":"Private image, original image, saved snippet ID, logo policy and usage","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/uploads":{"post":{"operationId":"uploadAdLibraryImage","summary":"Import an HTTPS attachment as an owned temporary reference or logo","description":"Requires ad-library:write. No credits. DNS-pinned download rejects private networks and Lahjty/Convex media URLs, including redirects. Use existing owned storage IDs directly. Non-animated PNG/JPEG/WebP, max 5 MB; reference max 16 megapixels; logo limits follow Brand Profile policy. Unattached uploads expire in 24 hours.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","maxLength":4000},"role":{"type":"string","enum":["reference","logo"],"default":"reference"}}},"examples":{"reference":{"value":{"role":"reference","url":"https://attachments.example/product.png"}}}}}},"responses":{"201":{"description":"Owned storage_id and upload metadata","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}},"delete":{"operationId":"discardAdLibraryUpload","summary":"Discard an owned unattached reference or logo","description":"Requires ad-library:write. Attached and foreign-account files cannot be discarded.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":100},"required":true,"in":"query","name":"storage_id"}],"responses":{"200":{"description":"Deletion outcome","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"}}}},"/capabilities":{"get":{"operationId":"getCapabilities","tags":["Discovery"],"summary":"List supported values, costs, and limits","security":[],"responses":{"200":{"description":"Current capabilities","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"}}}},"/copy-generations":{"post":{"operationId":"createCopyGeneration","tags":["Generation"],"summary":"Generate Arabic or English copy, or convert Arabic dialect","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyGenerationRequest"},"examples":{"arabicWhatsapp":{"summary":"Saudi WhatsApp AIDA copy with enforced keyword rules","value":{"type":"ad_copy","description":"Weekend offer: 20% off specialty coffee subscriptions","output_language":"ar","market":"SA","dialect":"saudi","platform":"whatsapp","tone":"warm","framework":"aida","audience":"specific","specific_audience":"Young professionals in Riyadh","keywords":["نهاية الأسبوع"],"required_keywords":["قهوة مختصة"],"excluded_keywords":["مجاني"],"call_to_action":"اطلب الآن"}},"englishCopy":{"summary":"English copy with UAE market context and no dialect","value":{"type":"ad_copy","description":"Same-day flower delivery launch offer","output_language":"en","market":"AE","platform":"instagram","tone":"warm","framework":"pas","call_to_action":"Order today"}},"iraqiConversion":{"summary":"Convert approved Saudi Arabic copy to Iraqi Arabic","value":{"type":"dialect_conversion","description":"قهوتك المفضلة توصلك لين باب البيت. اطلب الآن.","output_language":"ar","market":"IQ","source_dialect":"saudi","target_dialect":"iraqi","platform":"whatsapp"}}}}}},"responses":{"201":{"description":"Copy generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyGenerationResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/image-generations":{"post":{"operationId":"createImageGeneration","tags":["Generation"],"summary":"Generate and durably host a campaign image","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"},"examples":{"textFree":{"summary":"Text-free product showcase","value":{"prompt":"Premium specialty coffee weekend campaign","type":"product_showcase","style":"photorealistic","aspect_ratio":"1:1","resolution":"1K","visual_keywords":["coffee beans","Saudi coffee cup"],"excluded_visuals":["people","logos"],"include_text":false}},"arabicModelText":{"summary":"2K offer announcement with Arabic text rendered by the model","value":{"prompt":"Premium specialty coffee weekend campaign","type":"offer_announcement","aspect_ratio":"1:1","resolution":"2K","include_text":true,"overlay_text":"قهوتك، بطابعك","overlay_text_language":"ar"}},"englishModelText":{"summary":"Lifestyle image with English text rendered by the model","value":{"prompt":"Premium specialty coffee weekend campaign","type":"lifestyle","resolution":"1K","include_text":true,"overlay_text":"Weekend coffee offer","overlay_text_language":"en"}}}}}},"responses":{"201":{"description":"Image generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/speech-generations":{"post":{"operationId":"createSpeechGeneration","tags":["Generation"],"summary":"Generate and durably host Arabic or English speech","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechGenerationRequest"},"examples":{"whatsappVoice":{"summary":"Gulf Arabic WhatsApp voice asset","value":{"text":"طلبك صار جاهز، ونوصله لك بكرة بإذن الله.","dialect":"gulf","tone":"warm","platform":"whatsapp","delivery":"natural","content_type":"marketing","voice_profile":"warm_storyteller","external_customer_id":"merchant-91"}},"english":{"summary":"English transcript without Arabic dialect","value":{"text":"Your order is ready for delivery.","output_language":"en","delivery":"natural","voice_profile":"warm_storyteller"}}}}}},"responses":{"201":{"description":"Speech generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechGenerationResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}},"description":"Read the approved Arabic or English transcript exactly. output_language defaults to ar; Arabic dialect defaults to saudi. English must omit dialect. Costs 5 credits."}},"/campaigns":{"post":{"operationId":"createCampaign","tags":["Generation"],"summary":"Generate copy, optional image, optional speech, and a WhatsApp draft","description":"The cost is calculated from enabled deliverables. Copy is always included. Independent image and speech generation run in parallel after copy is ready. Synchronous v1 is atomic: if either enabled media deliverable fails, Lahjty deletes any successful sibling upload on a best-effort basis, refunds the complete campaign charge, and returns an error rather than a partial campaign.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignRequest"},"examples":{"whatsappCampaign":{"summary":"WhatsApp campaign with image","value":{"external_id":"my-app-campaign-1842","external_customer_id":"merchant-91","brief":{"description":"Launch a weekend bundle for our specialty coffee subscription","offer":"20% off through Saturday","objective":"Drive WhatsApp orders","dialect":"saudi","tone":"warm","platform":"whatsapp","audience":"specific","specific_audience":"Young professionals in Riyadh","keywords":["نهاية الأسبوع"],"required_keywords":["قهوة مختصة"],"excluded_keywords":["مجاني"],"call_to_action":"اطلب الآن"},"deliverables":{"copy":{"type":"ad_copy","framework":"aida"},"image":{"enabled":true,"type":"product_showcase","style":"photorealistic","aspect_ratio":"1:1","resolution":"1K","visual_keywords":["specialty coffee","Riyadh"],"excluded_visuals":["people","logos"],"include_text":true,"overlay_text":"اطلب الآن","overlay_text_language":"ar"},"speech":{"enabled":false,"voice_profile":"confident_announcer","delivery":"natural","content_type":"marketing"}}}}}}}},"responses":{"201":{"description":"Campaign generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/whatsapp-template-drafts":{"post":{"operationId":"createWhatsAppTemplateDraft","tags":["Templates"],"summary":"Generate a Meta-shaped WhatsApp template draft","description":"Returns an unsubmitted, deterministically preflighted payload. Lahjty does not submit to Meta and never represents a draft as approved.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateDraftRequest"},"examples":{"utilityArabic":{"summary":"Arabic utility order update with variable examples","value":{"name":"order_shipped","category":"UTILITY","output_language":"ar","language_code":"ar","market":"SA","dialect":"saudi","purpose":"Tell a customer that their order has shipped","customer_action_context":"The recipient placed the referenced order","variables":[{"name":"customer_name","example":"نورة"},{"name":"order_number","example":"A-1842"}],"header":"TEXT","footer":true,"buttons":[{"type":"QUICK_REPLY","text":"تواصل معنا"}]}},"marketingEnglish":{"summary":"English marketing template with opt-in context and no dialect","value":{"name":"weekend_coffee_offer","category":"MARKETING","output_language":"en","language_code":"en_GB","market":"AE","purpose":"Offer opted-in customers 20% off this weekend","opt_in_context":"Recipients opted in to WhatsApp promotions during checkout","variables":[{"name":"first_name","example":"Maya"}],"footer":true}}}}}},"responses":{"201":{"description":"Template draft generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateDraftResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/whatsapp-template-drafts/{draft_id}/outcomes":{"post":{"operationId":"reportWhatsAppTemplateOutcome","tags":["Templates"],"summary":"Report a Meta template outcome","description":"Stores an unverified partner-reported Meta lifecycle outcome for measurement and reconciliation. When REJECTED and submitted_payload_hash equals the original payload_hash, the response marks the draft as a refund candidate pending trusted Meta/provider evidence. Reporting an outcome never grants credits by itself. After Lahjty verifies that evidence, an authenticated administrative workflow applies the 2-credit refund exactly once.","security":[{"bearerAuth":[]}],"parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string","pattern":"^wtd_"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateOutcomeRequest"},"examples":{"rejectedUnchanged":{"summary":"Report an unchanged draft rejected by Meta","value":{"outcome":"REJECTED","meta_template_id":"123456789012345","provider_event_id":"provider-meta-event-3001","submitted_payload_hash":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","category":"UTILITY","reason":"Meta rejection reason","occurred_at":"2026-09-04T09:30:00Z"}}}}}},"responses":{"200":{"description":"Partner-reported outcome recorded; refund candidacy and verification state returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateOutcomeResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/usage":{"get":{"operationId":"getUsageSummary","tags":["Operations"],"summary":"Read shared balance and recent API usage","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}},"parameters":[{"name":"cursor","in":"query","required":false,"description":"Opaque next_cursor from the preceding page. Omit for the first page.","schema":{"type":"string","maxLength":8192}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}]}},"/requests/{request_id}":{"get":{"operationId":"getRequest","tags":["Operations"],"summary":"Inspect a recent generation request and its stored result","description":"Terminal request records and generated response payloads are retained for 30 days, then deleted. Durable Convex-stored media follows Lahjty's product retention lifecycle.","security":[{"bearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request status and result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRequest"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"lhj_live_…","description":"Create keys in the Lahjty Developer dashboard. Keys are shown once and stored only as SHA-256 hashes."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique value for this logical operation. Reusing it with the same body replays a terminal 2xx or 4xx response; reusing it with a different body returns 409. A 5xx response is never stored as the terminal replay. Retry the same body and key; if charge/refund reconciliation is still pending, Lahjty returns request_in_progress with Retry-After until recovery completes. Idempotency records are retained for 30 days.","schema":{"type":"string","minLength":1,"maxLength":200}}},"headers":{"RequestId":{"description":"Opaque Lahjty request identifier for logs and support.","schema":{"type":"string","pattern":"^req_"}},"ApiVersion":{"description":"The contract version that produced this response.","schema":{"type":"string","example":"2026-09-12"}}},"responses":{"Problem":{"description":"RFC 9457 problem response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"AdLibraryGenerationRequest":{"type":"object","required":["template_fields"],"additionalProperties":false,"properties":{"template_fields":{"type":"object","additionalProperties":{"type":"string","maxLength":4000},"description":"Exact approved values keyed by IDs from the prepared contract; each field's contract limit also applies."},"locale":{"type":"string","enum":["en","ar"],"default":"ar"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"],"default":"1:1"},"reference_storage_ids":{"type":"array","maxItems":2,"items":{"type":"string","maxLength":100}},"logo_storage_id":{"type":"string","maxLength":100},"logo_mode":{"type":"string","enum":["model","overlay","none"],"description":"Defaults to model when a logo is supplied, otherwise none. model sends the real logo as a separate image-model reference; overlay composites it deterministically; none ignores a supplied logo. model and overlay require logo_storage_id."},"palette":{"type":"object","additionalProperties":false,"properties":{"primary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}}}}},"CopyGenerationRequest":{"type":"object","additionalProperties":false,"required":["description"],"properties":{"type":{"type":"string","enum":["ad_copy","headlines","dialect_conversion"],"default":"ad_copy"},"description":{"type":"string","minLength":1,"maxLength":8000},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"$ref":"#/components/schemas/Market"},"dialect":{"$ref":"#/components/schemas/CopyDialect"},"source_dialect":{"$ref":"#/components/schemas/CopyDialect"},"target_dialect":{"$ref":"#/components/schemas/CopyDialect"},"platform":{"$ref":"#/components/schemas/Platform"},"tone":{"type":"string","default":"friendly","maxLength":100},"framework":{"$ref":"#/components/schemas/CopyFramework"},"audience":{"$ref":"#/components/schemas/Audience"},"specific_audience":{"type":"string","minLength":1,"maxLength":500,"description":"Required when audience is specific. This mirrors Lahjty Composer's custom-audience field."},"target_audience":{"type":"string","maxLength":500,"description":"Backward-compatible free-form audience detail. New integrations may prefer audience plus specific_audience."},"keywords":{"allOf":[{"$ref":"#/components/schemas/KeywordList"}],"description":"Preferred keywords. Lahjty uses them naturally when they improve the copy, but does not force awkward repetition."},"required_keywords":{"allOf":[{"$ref":"#/components/schemas/KeywordList"}],"description":"Words or phrases that must appear in every returned content variant. Lahjty retries once automatically and fails with content_rejected rather than returning non-compliant copy."},"excluded_keywords":{"allOf":[{"$ref":"#/components/schemas/KeywordList"}],"description":"Words or phrases that must not appear in any returned content variant. Matching is case-insensitive, Unicode-normalized, and Arabic-diacritic-insensitive."},"call_to_action":{"type":"string","maxLength":160},"brand_profile_id":{"type":"string","description":"A brand profile owned by the calling account."},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ImageGenerationRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":5,"maxLength":2000},"type":{"$ref":"#/components/schemas/ImageType"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"$ref":"#/components/schemas/Market"},"dialect":{"$ref":"#/components/schemas/CopyDialect"},"platform":{"$ref":"#/components/schemas/Platform"},"tone":{"type":"string","default":"friendly"},"style":{"$ref":"#/components/schemas/ImageStyle"},"aspect_ratio":{"$ref":"#/components/schemas/ImageAspectRatio"},"resolution":{"$ref":"#/components/schemas/ImageResolution"},"visual_keywords":{"allOf":[{"$ref":"#/components/schemas/VisualList"}],"description":"Visual subjects, settings, or concepts that the optimized image prompt must preserve."},"excluded_visuals":{"allOf":[{"$ref":"#/components/schemas/VisualList"}],"description":"Visual elements that the image prompt must explicitly exclude."},"include_text":{"type":"boolean","default":false,"description":"False forbids new advertising text, labels, signage, numbers, or pseudo-text. Supplied product packaging marks and an explicitly requested logo remain permitted. True requires overlay_text and sends the resolved phrase through Lahjty's Composer image prompt pipeline for the image model to render as part of the visual."},"overlay_text":{"type":"string","minLength":1,"maxLength":200,"description":"The concise marketing phrase supplied to the image model inside Lahjty's image prompt. Required when include_text is true and forbidden when it is false."},"overlay_text_language":{"$ref":"#/components/schemas/OverlayTextLanguage"},"brand_profile_id":{"type":"string","maxLength":200,"description":"An optional brand profile owned by the calling account. Brand context informs the visual without inventing a logo."},"reference_storage_ids":{"type":"array","maxItems":2,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100},"description":"Owned product/scene images imported with role reference. Product references and the logo use separate storage IDs."},"logo_storage_id":{"type":"string","minLength":1,"maxLength":100,"description":"Owned image imported with role logo."},"logo_mode":{"type":"string","enum":["model","overlay","none"],"description":"Defaults to model when a logo is supplied, otherwise none. model sends the real logo to the image model; overlay composites it deterministically; none ignores a supplied logo. model and overlay require logo_storage_id."},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SpeechGenerationRequest":{"type":"object","additionalProperties":false,"required":["text"],"allOf":[{"if":{"properties":{"output_language":{"const":"en"}},"required":["output_language"]},"then":{"not":{"properties":{"dialect":{}},"required":["dialect"]}}}],"properties":{"text":{"type":"string","minLength":1,"maxLength":6000},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"dialect":{"allOf":[{"$ref":"#/components/schemas/SpeechDialect"}],"description":"Arabic only, defaults to saudi when output_language is ar. Omit for English."},"tone":{"type":"string","default":"friendly"},"platform":{"$ref":"#/components/schemas/Platform"},"delivery":{"$ref":"#/components/schemas/SpeechDelivery"},"content_type":{"$ref":"#/components/schemas/SpeechContentType"},"voice_profile":{"$ref":"#/components/schemas/VoiceProfile"},"voice":{"allOf":[{"$ref":"#/components/schemas/Voice"}],"description":"Advanced provider voice override. Do not send it together with voice_profile."},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"CampaignRequest":{"type":"object","additionalProperties":false,"required":["brief"],"properties":{"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"brief":{"type":"object","additionalProperties":false,"required":["description"],"properties":{"description":{"type":"string","minLength":1,"maxLength":8000},"product":{"type":"string","maxLength":500},"offer":{"type":"string","maxLength":500},"objective":{"type":"string","maxLength":200},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"$ref":"#/components/schemas/Market"},"dialect":{"$ref":"#/components/schemas/CopyDialect"},"tone":{"type":"string","default":"friendly"},"platform":{"$ref":"#/components/schemas/Platform"},"audience":{"$ref":"#/components/schemas/Audience"},"specific_audience":{"type":"string","minLength":1,"maxLength":500},"target_audience":{"type":"string","maxLength":500},"call_to_action":{"type":"string","maxLength":160},"keywords":{"$ref":"#/components/schemas/KeywordList"},"required_keywords":{"$ref":"#/components/schemas/KeywordList"},"excluded_keywords":{"$ref":"#/components/schemas/KeywordList"},"brand_profile_id":{"type":"string"}}},"deliverables":{"type":"object","additionalProperties":false,"properties":{"copy":{"type":"object","additionalProperties":false,"properties":{"type":{"$ref":"#/components/schemas/CampaignCopyType"},"framework":{"$ref":"#/components/schemas/CopyFramework"}}},"image":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","default":true},"type":{"$ref":"#/components/schemas/ImageType"},"style":{"$ref":"#/components/schemas/ImageStyle"},"aspect_ratio":{"$ref":"#/components/schemas/ImageAspectRatio"},"resolution":{"$ref":"#/components/schemas/ImageResolution"},"visual_keywords":{"$ref":"#/components/schemas/VisualList"},"excluded_visuals":{"$ref":"#/components/schemas/VisualList"},"include_text":{"type":"boolean","default":false},"overlay_text":{"type":"string","minLength":1,"maxLength":200,"description":"When omitted in model-rendered text mode, the campaign uses brief.call_to_action, then brief.offer."},"overlay_text_language":{"$ref":"#/components/schemas/OverlayTextLanguage"}}},"speech":{"description":"Speech inherits brief.output_language. Arabic and English are supported; omit brief.dialect for English.","type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","default":false},"content_type":{"$ref":"#/components/schemas/SpeechContentType"},"voice_profile":{"$ref":"#/components/schemas/VoiceProfile"},"voice":{"$ref":"#/components/schemas/Voice"},"delivery":{"$ref":"#/components/schemas/SpeechDelivery"}}}}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"OutputLanguage":{"type":"string","enum":["ar","en"],"default":"ar","description":"Arabic supports dialect selection. English does not; omit dialect when output_language is en."},"Market":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 market. For Arabic, an omitted dialect is inferred from mapped markets; an unmapped supplied market uses classical. With neither field, the legacy Saudi fallback applies."},"CopyDialect":{"type":"string","enum":["classical","emirati","egyptian","gulf","saudi","levantine","iraqi"],"description":"Arabic only. Explicit dialect overrides market inference."},"SpeechDialect":{"type":"string","enum":["saudi","gulf","emirati","egyptian","classical","levantine"],"default":"saudi"},"Platform":{"type":"string","enum":["instagram","tiktok","linkedin","snapchat","google_search","twitter","whatsapp","facebook","telegram","website_landing_page","ecommerce_product_page","app_store_listing","email_subject_line"],"default":"whatsapp"},"CopyFramework":{"type":"string","enum":["none","aida","pas","fab","story"],"default":"none","description":"Copywriting structure. Non-none values apply only to ad_copy."},"CampaignCopyType":{"type":"string","enum":["ad_copy","headlines"],"default":"ad_copy"},"Audience":{"type":"string","enum":["everyone","specific","all_genders","female","male","children","teenagers","young_adults","families","professionals","adults","seniors","beginners","experts","students","customers","employees","developers","managers"]},"ImageType":{"type":"string","enum":["campaign_visual","product_showcase","lifestyle","offer_announcement","brand_awareness"],"default":"campaign_visual","description":"The marketing purpose and composition intent. This is separate from style, which controls the visual treatment."},"ImageStyle":{"type":"string","enum":["photorealistic","illustration","flat-design","3d-render","watercolor","minimalist"],"default":"photorealistic"},"ImageAspectRatio":{"type":"string","enum":["1:1","1:4","1:8","2:3","3:2","3:4","4:1","4:3","4:5","5:4","8:1","9:16","16:9","21:9"],"default":"1:1"},"ImageResolution":{"type":"string","enum":["512","1K","2K"],"default":"1K","description":"Normalized output resolution tier sent to the image provider. Actual pixel width and height are returned in image.width and image.height."},"OverlayTextLanguage":{"type":"string","enum":["auto","ar","en"],"default":"auto","description":"auto preserves the supplied phrase and detects its script. ar or en translates a mismatched source phrase before including it in the Composer image prompt."},"KeywordList":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":80}},"VisualList":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":120}},"SpeechDelivery":{"type":"string","enum":["auto","natural","reel_voiceover","conversational","professional","energetic","storytelling"],"default":"natural"},"SpeechContentType":{"type":"string","enum":["marketing","general"],"default":"marketing"},"VoiceProfile":{"type":"string","enum":["bright_presenter","warm_storyteller","confident_announcer","modern_narrator","premium_narrator"],"default":"confident_announcer","description":"Recommended Lahjty Composer voice persona. Omit voice when using this field."},"Voice":{"type":"string","enum":["Zephyr","Puck","Charon","Kore","Fenrir","Leda","Orus","Aoede","Callirrhoe","Autonoe","Enceladus","Iapetus","Umbriel","Algieba","Despina","Erinome","Algenib","Rasalgethi","Laomedeia","Achernar","Alnilam","Schedar","Gacrux","Pulcherrima","Achird","Zubenelgenubi","Vindemiatrix","Sadachbia","Sadaltager","Sulafat"]},"Metadata":{"type":"object","maxProperties":20,"propertyNames":{"minLength":1,"maxLength":64},"additionalProperties":{"type":"string","maxLength":500}},"GenerationEnvelope":{"type":"object","required":["request_id","usage"],"properties":{"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/GenerationUsage"}}},"GenerationUsage":{"type":"object","required":["credits_used","balance_after"],"properties":{"credits_used":{"type":"number"},"balance_after":{"type":"number"}}},"CopyVariant":{"type":"object","required":["index","content","angle","recommended","keyword_compliance"],"properties":{"index":{"type":"integer","minimum":1,"maximum":3},"content":{"type":"string","minLength":1,"maxLength":12000,"description":"Up to 4000 characters for copy/headlines or 12000 for faithful dialect conversion. Blank, duplicate copy variants and basic script mismatches are rejected after one repair. These checks do not certify fluency or factual truth."},"angle":{"type":"string"},"call_to_action":{"type":["string","null"]},"recommended":{"type":"boolean"},"keyword_compliance":{"type":"object","required":["passed","matched_required","missing_required","matched_excluded"],"properties":{"passed":{"const":true},"matched_required":{"$ref":"#/components/schemas/KeywordList"},"missing_required":{"type":"array","maxItems":0},"matched_excluded":{"type":"array","maxItems":0}}}}},"CopyResult":{"type":"object","required":["id","object","external_id","external_customer_id","metadata","type","output_language","market","dialect","dialect_source","variants","keyword_policy","controls","engine_version"],"properties":{"id":{"type":"string","pattern":"^cpy_"},"object":{"const":"copy_generation"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"type":{"type":"string"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"type":["string","null"]},"dialect":{"type":"string","description":"Arabic dialect identifier. English responses return the compatibility sentinel `none`; English requests do not accept a dialect."},"dialect_source":{"type":["string","null"],"enum":["explicit","market","fallback",null]},"platform":{"type":"string"},"variants":{"type":"array","minItems":1,"maxItems":3,"items":{"$ref":"#/components/schemas/CopyVariant"}},"keyword_policy":{"type":"object","required":["preferred","required","excluded","enforced"],"properties":{"preferred":{"$ref":"#/components/schemas/KeywordList"},"required":{"$ref":"#/components/schemas/KeywordList"},"excluded":{"$ref":"#/components/schemas/KeywordList"},"enforced":{"const":true}}},"controls":{"type":"object","required":["framework","audience","target_audience","tone","call_to_action","brand_profile_id"],"properties":{"framework":{"type":["string","null"]},"audience":{"type":["string","null"]},"target_audience":{"type":["string","null"]},"tone":{"type":["string","null"]},"call_to_action":{"type":["string","null"]},"brand_profile_id":{"type":["string","null"]}}},"engine_version":{"type":"string"}}},"CopyGenerationResponse":{"allOf":[{"$ref":"#/components/schemas/CopyResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"ImageResult":{"type":"object","required":["id","object","external_id","external_customer_id","metadata","status","output_language","market","dialect","dialect_source","image","aspect_ratio","resolution","type","style","brand_profile_id","text_policy","visual_policy","prompt_plan","engine_version"],"properties":{"id":{"type":"string","pattern":"^img_"},"object":{"const":"image_generation"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"const":"completed"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"type":["string","null"]},"dialect":{"oneOf":[{"$ref":"#/components/schemas/CopyDialect"},{"type":"null"}]},"dialect_source":{"type":["string","null"],"enum":["explicit","market","fallback",null]},"image":{"type":"object","required":["url","mime_type","width","height","bytes"],"properties":{"url":{"type":"string","format":"uri"},"mime_type":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"bytes":{"type":"integer"}}},"aspect_ratio":{"type":"string"},"resolution":{"$ref":"#/components/schemas/ImageResolution"},"type":{"$ref":"#/components/schemas/ImageType"},"style":{"type":"string"},"brand_profile_id":{"type":["string","null"]},"reference_images_used":{"type":"integer","minimum":0,"maximum":2},"logo_policy":{"type":"object","properties":{"mode":{"type":"string","enum":["model","deterministic_overlay","none"]},"logo_overlaid":{"type":"boolean"},"logo_sent_to_model":{"type":"boolean"},"logo_storage_id":{"type":["string","null"],"description":"Supplied owned upload ID when used; null when omitted. Generic generation does not create a retained History logo copy."}}},"text_policy":{"type":"object","required":["mode","content","language","translated","deterministic","renderer"],"properties":{"mode":{"type":"string","enum":["none","model"]},"content":{"type":["string","null"]},"language":{"type":["string","null"],"enum":["ar","en",null]},"translated":{"type":"boolean"},"deterministic":{"type":"boolean","const":false,"description":"False because the image model, rather than a post-render compositor, renders the phrase."},"renderer":{"type":["string","null"],"enum":["image_model",null]}}},"visual_policy":{"type":"object","required":["required","excluded"],"properties":{"required":{"$ref":"#/components/schemas/VisualList"},"excluded":{"$ref":"#/components/schemas/VisualList"}}},"prompt_plan":{"type":"object","required":["prompt","composition","typography","culturalNotes","negativePrompt"],"properties":{"prompt":{"type":"string"},"composition":{"type":["string","null"]},"typography":{"type":["string","null"]},"culturalNotes":{"type":["string","null"]},"negativePrompt":{"type":["string","null"]}}},"engine_version":{"type":"string"}}},"ImageGenerationResponse":{"allOf":[{"$ref":"#/components/schemas/ImageResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"SpeechResult":{"type":"object","required":["id","object","external_id","external_customer_id","metadata","status","audio","voice","voice_profile","delivery","content_type","prompt_context_source","output_language","dialect","provider","fallback_used","engine_version"],"properties":{"id":{"type":"string","pattern":"^spc_"},"object":{"const":"speech_generation"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"const":"completed"},"audio":{"type":"object","required":["url","mime_type","bytes","duration_seconds"],"properties":{"url":{"type":"string","format":"uri"},"mime_type":{"type":"string"},"bytes":{"type":"integer"},"duration_seconds":{"type":["number","null"]}}},"voice":{"$ref":"#/components/schemas/Voice"},"voice_profile":{"type":["string","null"]},"delivery":{"$ref":"#/components/schemas/SpeechDelivery"},"content_type":{"$ref":"#/components/schemas/SpeechContentType"},"prompt_context_source":{"type":"string","enum":["optimized","fallback","provider_voice"]},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"dialect":{"type":["string","null"],"description":"Arabic dialect or null for English."},"provider":{"type":"string","enum":["google-ai-studio","google-vertex"]},"fallback_used":{"type":"boolean"},"engine_version":{"type":"string"}}},"SpeechGenerationResponse":{"allOf":[{"$ref":"#/components/schemas/SpeechResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"WhatsAppTemplateCategory":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"WhatsAppTemplateDraftRequest":{"type":"object","additionalProperties":false,"required":["name","category","purpose"],"properties":{"name":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-z0-9_]+$"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"language_code":{"type":"string","enum":["ar","en","en_GB","en_US"],"description":"Supported Meta template locale code. It must match output_language and defaults to ar or en. Market affects generation context, not this code."},"market":{"$ref":"#/components/schemas/Market"},"dialect":{"$ref":"#/components/schemas/CopyDialect"},"purpose":{"type":"string","minLength":10,"maxLength":2000},"customer_action_context":{"type":"string","minLength":5,"maxLength":1000,"description":"Required for UTILITY; describe the specific user-initiated transaction or request."},"opt_in_context":{"type":"string","minLength":5,"maxLength":1000,"description":"Required for MARKETING; describe how recipients consented to these messages."},"variables":{"type":"array","maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["name","example"],"properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"},"example":{"type":"string","minLength":1,"maxLength":500}}}},"header":{"type":"string","enum":["NONE","TEXT"],"default":"NONE"},"footer":{"type":"boolean","default":false},"buttons":{"type":"array","maxItems":3,"items":{"oneOf":[{"$ref":"#/components/schemas/WhatsAppQuickReplyButton"},{"$ref":"#/components/schemas/WhatsAppUrlButton"},{"$ref":"#/components/schemas/WhatsAppPhoneButton"}]}},"authentication":{"type":"object","additionalProperties":false,"properties":{"add_security_recommendation":{"type":"boolean","default":true},"code_expiration_minutes":{"type":"integer","minimum":1,"maximum":90,"default":10}}},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"WhatsAppQuickReplyButton":{"type":"object","additionalProperties":false,"required":["type","text"],"properties":{"type":{"const":"QUICK_REPLY"},"text":{"type":"string","minLength":1,"maxLength":25}}},"WhatsAppUrlButton":{"type":"object","additionalProperties":false,"required":["type","text","url"],"properties":{"type":{"const":"URL"},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","format":"uri","maxLength":2000}}},"WhatsAppPhoneButton":{"type":"object","additionalProperties":false,"required":["type","text","phone_number"],"properties":{"type":{"const":"PHONE_NUMBER"},"text":{"type":"string","minLength":1,"maxLength":25},"phone_number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}}},"WhatsAppTemplateDraftResult":{"type":"object","required":["id","object","status","external_id","external_customer_id","metadata","output_language","market","dialect","dialect_source","meta_payload","payload_hash","compliance","provider_usage"],"properties":{"id":{"type":"string","pattern":"^wtd_"},"object":{"const":"whatsapp_template_draft"},"status":{"const":"UNSUBMITTED"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"type":["string","null"]},"dialect":{"oneOf":[{"$ref":"#/components/schemas/CopyDialect"},{"type":"null"}]},"dialect_source":{"type":["string","null"],"enum":["explicit","market","fallback",null]},"meta_payload":{"type":"object","required":["name","language","category","components"],"properties":{"name":{"type":"string"},"language":{"type":"string"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"components":{"type":"array","items":{"type":"object"}}}},"payload_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"compliance":{"type":"object","required":["ready_for_submission","findings","final_decision_owner"],"properties":{"ready_for_submission":{"const":true},"findings":{"type":"array","items":{"type":"object"}},"final_decision_owner":{"const":"META"}}},"provider_usage":{"type":"object"}}},"WhatsAppTemplateDraftResponse":{"allOf":[{"$ref":"#/components/schemas/WhatsAppTemplateDraftResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"WhatsAppTemplateOutcomeRequest":{"type":"object","additionalProperties":false,"required":["outcome","meta_template_id","provider_event_id","submitted_payload_hash"],"properties":{"outcome":{"type":"string","enum":["SUBMITTED","APPROVED","REJECTED","RECLASSIFIED","PAUSED","DISABLED"]},"meta_template_id":{"type":"string","maxLength":200},"provider_event_id":{"type":"string","maxLength":200,"description":"Partner-supplied correlation and deduplication identifier. It is not accepted as proof of a Meta outcome."},"submitted_payload_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"reason":{"type":"string","maxLength":2000},"occurred_at":{"type":"string","format":"date-time"}}},"WhatsAppTemplateOutcomeResponse":{"allOf":[{"$ref":"#/components/schemas/GenerationEnvelope"},{"type":"object","required":["object","draft_id","outcome","unchanged","category","refund"],"properties":{"object":{"const":"whatsapp_template_outcome"},"draft_id":{"type":"string"},"outcome":{"type":"string"},"unchanged":{"type":"boolean"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"refund":{"type":"object","required":["candidate","eligible","status","credits","balance_after","verification_required"],"properties":{"candidate":{"type":"boolean","description":"True when the reported outcome is REJECTED and the submitted hash matches the generated draft. A candidate is not yet eligible for credit until evidence is verified."},"eligible":{"type":"boolean"},"status":{"type":"string","enum":["NOT_ELIGIBLE","PENDING_VERIFICATION","REFUNDED"]},"credits":{"type":"number"},"balance_after":{"type":["number","null"]},"verification_required":{"type":"boolean"}}}}}]},"WhatsAppTemplateDraft":{"type":"object","required":["status","header","body","footer","buttons","warnings"],"properties":{"status":{"const":"draft"},"header":{"type":["string","null"]},"body":{"type":"string"},"footer":{"type":["string","null"]},"buttons":{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"const":"quick_reply"},"text":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"}}}},"CampaignResponse":{"allOf":[{"$ref":"#/components/schemas/GenerationEnvelope"},{"type":"object","required":["id","object","status","external_id","external_customer_id","metadata","output_language","market","dialect","dialect_source","copy","whatsapp_template","image","speech","engine_version"],"properties":{"id":{"type":"string","pattern":"^cmp_"},"object":{"const":"campaign"},"status":{"const":"completed"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"type":["string","null"]},"dialect":{"oneOf":[{"$ref":"#/components/schemas/CopyDialect"},{"type":"null"}]},"dialect_source":{"type":["string","null"],"enum":["explicit","market","fallback",null]},"copy":{"$ref":"#/components/schemas/CopyResult"},"whatsapp_template":{"$ref":"#/components/schemas/WhatsAppTemplateDraft"},"image":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"null"}]},"speech":{"oneOf":[{"$ref":"#/components/schemas/SpeechResult"},{"type":"null"}]},"engine_version":{"type":"string"}}}]},"Problem":{"type":"object","required":["type","title","status","code","detail","request_id"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","enum":["invalid_request","authentication_failed","paid_plan_required","permission_denied","not_found","insufficient_credits","rate_limit_exceeded","idempotency_key_required","idempotency_conflict","request_in_progress","stale_request_recovered","content_rejected","provider_unavailable","internal_error"]},"detail":{"type":"string"},"request_id":{"type":"string"},"instance":{"type":"string"},"errors":{}}},"ApiUsageAttempt":{"type":"object","required":["id","operation","status","credits","credits_charged","credits_refunded","refund_pending","created_at"],"properties":{"id":{"type":"string"},"operation":{"type":"string","examples":["copy.ad_copy","campaign.generate"]},"status":{"type":"string","enum":["processing","succeeded","failed","retryable"],"description":"retryable is a legacy attempt awaiting reconciliation."},"credits":{"type":"integer","minimum":0},"credits_charged":{"type":"boolean"},"credits_refunded":{"type":"boolean"},"refund_pending":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ApiRequest":{"type":"object","required":["id","operation","status","credits","credits_charged","credits_refunded","refund_pending","created_at","object","status_code","error_code","updated_at","result"],"properties":{"id":{"type":"string"},"operation":{"type":"string","examples":["copy.ad_copy","campaign.generate"]},"status":{"type":"string","enum":["processing","succeeded","failed","retryable"],"description":"retryable is a legacy attempt awaiting reconciliation."},"credits":{"type":"integer","minimum":0},"credits_charged":{"type":"boolean"},"credits_refunded":{"type":"boolean"},"refund_pending":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"object":{"type":"string","const":"api_request"},"status_code":{"type":["integer","null"]},"error_code":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"},"result":{"type":["object","null"],"description":"Stored generation response or Problem response. Null while processing."}}},"UsageSummary":{"type":"object","required":["object","plan","balance","recent_requests","successful_requests","credits_used","summary_scope","summary_limit","summary_truncated","credits_used_basis","retention_days","is_done","next_cursor","requests"],"properties":{"object":{"type":"string","const":"usage_summary"},"plan":{"type":"string"},"balance":{"type":"number"},"recent_requests":{"type":"integer"},"successful_requests":{"type":"integer"},"credits_used":{"type":"number","description":"Gross successful generation credits in the latest 50 retained attempts; excludes subsequent template outcome refunds."},"summary_scope":{"type":"string","const":"latest_50_attempts"},"summary_limit":{"type":"integer","const":50},"summary_truncated":{"type":"boolean"},"credits_used_basis":{"type":"string","const":"gross_successful_generation_credits"},"retention_days":{"type":"integer","const":30},"is_done":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"requests":{"type":"array","items":{"$ref":"#/components/schemas/ApiUsageAttempt"}}}}}}}