{"openapi":"3.1.0","info":{"title":"Lahjty API","version":"2026-10-10","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 billable POST operations require an Idempotency-Key; informational context and quote preflights are read-only POSTs and do not consume credits. 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 an ad or image-lib- ID in q) returns only that item or 404. Invalid industry/sector/style/kind values return 422; use the enumerated values or omit the filter. Every item has kind: product_photo_format (Lahjty's curated product-photo formats, image-lib-* IDs: ready without a preparation charge, need 1-2 owned product photos uploaded with role reference, keep the product's own printed label; preview_url is the format's sample ad made with a fictional product), lahjty_template (Lahjty's original templates, ready), analyzed_ad (imported ad with a shipped contract, ready) or gallery_ad (imported ad that needs a one-time paid preparation unless already prepared; read its detail). Items also carry requires_product_photo and product_photo_format (null except for product-photo formats: photo_subject product|dish|screen, product_photos {required, min, max, upload_role}, keeps_product_label, palette_role scene|accent|none, visible_text_field_ids, text_free, suggested_aspect_ratio). Use kind=product_photo_format for a physical product the user can photograph.","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"]}},{"in":"query","name":"kind","description":"Optional item kind; product_photo_format returns only Lahjty's curated product-photo formats. Omit or all for every kind.","schema":{"type":"string","enum":["all","product_photo_format","lahjty_template","analyzed_ad","gallery_ad"]}}],"responses":{"200":{"description":"Catalog items with kind, product-photo format metadata, 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. Accepts image-lib-* product-photo format IDs: ad has the same kind, requires_product_photo and product_photo_format fields as search; preparation is ready with analysis_credits 0; contract.fields lists the editable fields (product name, plus a headline or other fields when the format uses them) and contract.reference_requirement is required. contract.composer.aspectRatio is the format's authored canvas; use ad.product_photo_format.suggested_aspect_ratio, which generation accepts.","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. Product-photo formats (image-lib-*), Lahjty templates and analyzed ads are always prepared: this returns their ready contract with no analysis and charged 0. 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 of the requested resolution: 5 credits at 1K (the default) and 8 credits at 2K. 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. Product-photo formats (image-lib-*) need at least one owned product photo in reference_storage_ids (400 before any charge otherwise) and keep the text printed on that product. palette applies according to the format's palette_role: scene colors the backdrop or set, accent colors only small accents, none keeps the scene's colors. Copy verification still requires every approved headline value and rejects added text; leftover text made only of whole words read from the supplied product photo is the product's own label and is accepted, and text_policy.product_label is preserved.","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, rendered resolution and usage. Responses replayed from before resolution was added omit it.","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"}}}},"/context/website":{"post":{"operationId":"getWebsiteContext","tags":["Discovery"],"summary":"Extract bounded, unverified context from one public website","description":"Requires context:read. Fetches one public HTTP(S) URL with bounded size, timeout and redirect/SSRF checks. This is an informational read: it does not persist a Brand Profile, generate content, upload assets, or spend credits. Returned source facts are unverified references and must be reviewed before advertising claims or logo use.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebsiteContextRequest"},"examples":{"publicSite":{"value":{"url":"https://example.com/product"}}}}}},"responses":{"200":{"description":"Bounded website context and source references","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebsiteContextResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/brand-profiles":{"get":{"operationId":"listBrandProfiles","tags":["Discovery"],"summary":"List Brand Profiles owned by the calling account","description":"Requires brands:read. Returns least-privilege summaries for profiles owned by the authenticated account. Pagination cursors are opaque and account-scoped.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ContextCursor"},{"$ref":"#/components/parameters/ContextLimit"}],"responses":{"200":{"description":"Owned Brand Profile summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandProfileListResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/brand-profiles/{brand_profile_id}":{"get":{"operationId":"getBrandProfile","tags":["Discovery"],"summary":"Read one owned Brand Profile and recent source resources","description":"Requires brands:read. The profile ID is resolved within the authenticated account; foreign or unknown IDs return not_found without disclosure.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brand_profile_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Owned Brand Profile context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandProfileResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/quote":{"post":{"operationId":"validateAndQuote","tags":["Discovery"],"summary":"Validate a requested operation and return its current quote","description":"Requires the write scope associated with the requested operation: copy:write, images:write, speech:write, campaigns:write, templates:write, or ad-library:write. Validates the supplied operation without crawling a website, generating media, reserving credits, or creating a saved result. A quote is informational and must be revalidated if the brief, account, entitlement, assets, or pricing changes. It is not proof of user approval or available balance. Image line items report 5 credits at 1K or 8 credits at 2K according to the requested resolution; an image edit without a resolution uses its source image's resolution.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"},"examples":{"oneCopy":{"value":{"operation":"copy","request":{"description":"A short Saudi Arabic Instagram promotion for a cardamom latte","output_language":"ar","dialect":"saudi","platform":"instagram","count":1}}},"campaign":{"value":{"operation":"campaign","request":{"brief":{"description":"Launch a weekend coffee subscription offer","output_language":"en","platform":"instagram"},"deliverables":{"copy":{"enabled":true},"image":{"enabled":false},"speech":{"enabled":false}}}}}}}}},"responses":{"200":{"description":"Validation status and current quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/capabilities":{"get":{"operationId":"getCapabilities","tags":["Discovery"],"summary":"List supported values, costs, and limits","description":"Public and free. credit_costs lists each operation's price, including image and image_2k, image_edit and image_edit_2k. image_controls.credits_by_resolution, image_edits.credits_by_resolution and ad_library.generation_credits_by_resolution map each resolution tier to its credits (1K: 5, 2K: 8); the numeric image_edits.credits and ad_library.generation_credits remain the 1K price.","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","description":"Requires images:write. Costs 5 credits at 1K (the default) and 8 credits at 2K. The deprecated 512 tier is rendered and charged as 1K. A failed attempt refunds exactly the charged amount, and a replay with the same Idempotency-Key never charges again.","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"}}}},"/image-edits":{"post":{"operationId":"createImageEdit","tags":["Generation"],"summary":"Edit an owned, completed image result with a conversational instruction, or make it in another size","description":"Requires images:write. Costs 5 credits at 1K and 8 credits at 2K, the same as an image edit in the Lahjty dashboard. The charge follows the rendered resolution: the request's resolution, otherwise the source image's recorded resolution, otherwise 1K. source_request_id must be the request_id of an earlier completed image generation, image edit, Ad Library generation, or campaign whose image deliverable completed, owned by the calling account. Before any debit, Lahjty resolves that source, reads its saved image from Lahjty storage, and validates owned references and the logo: an unknown or foreign source returns 404, a failed or image-less source returns 422, and a still-processing source returns a retryable 409, all without a charge. The saved image and the instruction go to the image model with an edit prompt that preserves everything the instruction does not mention; there is no prompt optimizer and no copy verification. A resize (resize true, or no instruction) makes the same ad as a 4:5 feed post, a 1:1 square or a 9:16 Story and changes nothing else: Lahjty writes the instruction itself, and the new size is read back like a new image. Its words are compared with the source's (the copy the source's own text check verified, otherwise a careful reading of the source, never shown to the image model) and the whole ad passes the visual check, with the product compared to the source image. A failed check renders once more with a correction; if it still fails, the request fails with 422 content_rejected (errors.reason ad_copy_mismatch or ad_check_failed), is refunded and saves no image. A resize to the source's own size returns 422 invalid_request before any charge. Any logo already in the picture stays part of the design. A free account's mark on the source is covered before the image is sent, and the result gets its own. The source aspect ratio and resolution are kept unless aspect_ratio or resolution is supplied. Accounts without paid access receive the Lahjty watermark and no deterministic logo overlay. The result reuses the image_generation object and adds edit_of. Replay, durable save, refund on failure, and GET /requests/{request_id} recovery behave as for image generations.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageEditRequest"},"examples":{"whiteBackground":{"summary":"Change only the background","value":{"source_request_id":"req_01jimagesource","instruction":"Make the background plain white and keep the product unchanged.","output_language":"ar"}},"swapProduct":{"summary":"Place the customer's own product photo","value":{"source_request_id":"req_01jimagesource","instruction":"Replace the bottle with the product in the reference photo.","reference_storage_ids":["owned_reference_storage_id"]}},"biggerLogo":{"summary":"Make the supplied logo larger","value":{"source_request_id":"req_01jimagesource","instruction":"Make the logo bigger.","logo_storage_id":"owned_logo_storage_id","logo_mode":"model"}},"storyVersion":{"summary":"The same ad as a 9:16 Story, checked like a new image","value":{"source_request_id":"req_01jimagesource","resize":true,"aspect_ratio":"9:16"}}}}}},"responses":{"201":{"description":"Image edited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageEditResponse"}}}},"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 costs 2 credits, an image 5 credits at 1K or 8 credits at 2K (deliverables.image.resolution), and speech 5 credits, so a campaign costs 2 to 15 credits. Copy is always included. Independent image and speech generation run in parallel after copy is ready. If an enabled image or speech deliverable fails after copy succeeds, Lahjty retains the successful deliverables, refunds the failed child credits, and returns HTTP 207 with status partial. The partial receipt includes credits_refunded, refund_pending, and net usage; reuse the same Idempotency-Key to replay this terminal receipt, and inspect the stored request before starting any new attempt.","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"}}}},"207":{"description":"Campaign partially generated; failed child credits were refunded","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPartialResponse"}}}},"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","description":"The top-level credits_used counter remains the legacy gross successful-generation total for the latest 50 retained attempts. Use net_credits_used and each request's net_credits/partial_refund_credits to account for partial child refunds; pagination still returns every retained attempt.","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}},"ContextCursor":{"name":"cursor","in":"query","required":false,"description":"Opaque account-scoped cursor returned as next_cursor. Omit for the first page.","schema":{"type":"string","minLength":1,"maxLength":8192}},"ContextLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"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-10-10"}}},"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","4:5","16:9","9:16","4:3","3:4"],"default":"1:1"},"resolution":{"type":"string","enum":["1K","2K"],"default":"1K","description":"Output resolution tier. 1K costs 5 credits and 2K costs 8 credits. The response reports the rendered resolution."},"reference_storage_ids":{"type":"array","maxItems":2,"items":{"type":"string","maxLength":100},"description":"Owned product photos uploaded with role reference. Product-photo formats (kind product_photo_format) require one or two photos of the same product."},"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,"description":"Brand colors. For product-photo formats they follow the format's palette_role and are ignored when it is none.","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},"count":{"type":"integer","minimum":1,"maximum":3,"default":3,"description":"Number of distinct returned variants. Direct Partner API callers retain the historical default of three; the MCP layer may set one for an explicit one-copy workflow."},"max_characters":{"type":"integer","minimum":1,"maximum":4000,"description":"Maximum characters for each returned copy/headline variant. Omit to use the route default."},"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":{"enabled":{"type":"boolean","default":true},"type":{"$ref":"#/components/schemas/CampaignCopyType"},"framework":{"$ref":"#/components/schemas/CopyFramework"},"count":{"type":"integer","minimum":1,"maximum":3,"default":3},"max_characters":{"type":"integer","minimum":1,"maximum":4000}}},"image":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","default":false,"description":"Images are opt-in for campaigns; omit or set false to generate copy only."},"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"},"reference_storage_ids":{"type":"array","maxItems":2,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100},"description":"Owned product/scene reference uploads. Do not use a logo ID as a product reference."},"logo_storage_id":{"type":"string","minLength":1,"maxLength":100,"description":"Owned logo upload ID."},"logo_mode":{"type":"string","enum":["model","overlay","none"],"description":"Defaults to model when a logo is supplied, otherwise none. model and overlay require logo_storage_id."},"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. Speech is opt-in for campaigns.","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"}}},"WebsiteContextRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","minLength":1,"maxLength":4000,"description":"One public HTTP(S) website URL. A missing scheme is normalized to https; credentials and private destinations are rejected."}}},"WebsiteContextResponse":{"type":"object","additionalProperties":false,"required":["object","status","requested_url","final_url","retrieved_at","identity","source_facts","asset_candidates","missing_fields","extraction_warnings","user_corrections","creative_suggestions","persisted","generation_requested"],"properties":{"object":{"const":"website_context"},"status":{"type":"string","enum":["ready","partial","blocked","unavailable"]},"requested_url":{"type":"string","format":"uri"},"final_url":{"type":"string","format":"uri"},"retrieved_at":{"type":"string","format":"date-time"},"identity":{"type":"object","additionalProperties":false,"required":["name","description"],"properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]}}},"source_facts":{"type":"array","items":{"$ref":"#/components/schemas/WebsiteSourceFact"}},"asset_candidates":{"type":"array","items":{"$ref":"#/components/schemas/WebsiteAssetCandidate"}},"missing_fields":{"type":"array","items":{"type":"string"}},"extraction_warnings":{"type":"array","items":{"type":"string"}},"user_corrections":{"type":"array","maxItems":0,"description":"Reserved for a future explicit correction flow; website extraction never invents corrections."},"creative_suggestions":{"type":"array","maxItems":0,"description":"Reserved for a future explicit suggestion flow; extraction does not generate creative output."},"persisted":{"const":false},"generation_requested":{"const":false}}},"WebsiteSourceFact":{"type":"object","additionalProperties":false,"required":["field","value","source"],"properties":{"field":{"type":"string","enum":["brand_name","description","page_text"]},"value":{"type":"string","maxLength":4000},"source":{"type":"object","additionalProperties":false,"required":["url","locator"],"properties":{"url":{"type":"string","format":"uri"},"locator":{"type":"string"}}}}},"WebsiteAssetCandidate":{"type":"object","additionalProperties":false,"required":["url","role","confidence","source_url"],"properties":{"url":{"type":"string","format":"uri"},"role":{"const":"icon_candidate"},"confidence":{"const":"low"},"source_url":{"type":"string","format":"uri"}}},"BrandProfileSummary":{"type":"object","additionalProperties":false,"required":["id","name","industry","description","summary","website","website_icon_available","logo_available","primary_color","secondary_color","accent_color","brand_strength","social_links","created_at","updated_at"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"industry":{"type":["string","null"]},"description":{"type":"string"},"summary":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"website_icon_available":{"type":"boolean"},"logo_available":{"type":"boolean"},"primary_color":{"type":["string","null"]},"secondary_color":{"type":["string","null"]},"accent_color":{"type":["string","null"]},"brand_strength":{"type":"string","enum":["subtle","balanced","strong"]},"social_links":{"$ref":"#/components/schemas/BrandSocialLinks"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"BrandSocialLinks":{"type":"object","additionalProperties":false,"required":["linkedin","instagram","facebook","twitter","tiktok"],"properties":{"linkedin":{"type":["string","null"],"format":"uri"},"instagram":{"type":["string","null"],"format":"uri"},"facebook":{"type":["string","null"],"format":"uri"},"twitter":{"type":["string","null"],"format":"uri"},"tiktok":{"type":["string","null"],"format":"uri"}}},"BrandProfileResource":{"type":"object","additionalProperties":false,"required":["id","title","source_type","source_url","content_length","content","created_at"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"source_type":{"type":"string"},"source_url":{"type":["string","null"],"format":"uri"},"content_length":{"type":"integer","minimum":0},"content":{"type":"string","maxLength":1500},"created_at":{"type":"string","format":"date-time"}}},"BrandProfileListResponse":{"type":"object","additionalProperties":false,"required":["object","profiles","is_done","next_cursor"],"properties":{"object":{"const":"brand_profile_list"},"profiles":{"type":"array","items":{"$ref":"#/components/schemas/BrandProfileSummary"}},"is_done":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"BrandProfileResponse":{"allOf":[{"$ref":"#/components/schemas/BrandProfileSummary"},{"type":"object","required":["object","resources"],"properties":{"object":{"const":"brand_profile"},"resources":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/BrandProfileResource"}}}}]},"QuoteRequest":{"type":"object","additionalProperties":false,"required":["operation"],"properties":{"operation":{"type":"string","enum":["copy","image","speech","campaign","whatsapp_template","ad_library_prepare","ad_library_generate","image_edit"]},"request":{"type":"object","additionalProperties":true,"default":{},"description":"Operation-specific fields from the matching generation request schema. The quote validates the payload and returns needs_input for incomplete fields; it does not choose an output language or other missing user intent."}}},"QuoteResponse":{"type":"object","additionalProperties":false,"required":["object","api_version","quote_version","operation","status","quote","authorization","missing_fields","conflicts","allowed_next_actions","generation_allowed","confirmation_policy","confirmation_required","side_effects"],"properties":{"object":{"const":"validation_quote"},"api_version":{"type":"string"},"quote_version":{"type":"string"},"operation":{"type":"string","enum":["copy","image","speech","campaign","whatsapp_template","ad_library_prepare","ad_library_generate","image_edit"]},"status":{"type":"string","enum":["ready","needs_input"]},"quote":{"oneOf":[{"$ref":"#/components/schemas/Quote"},{"type":"null"}]},"authorization":{"$ref":"#/components/schemas/QuoteAuthorization"},"missing_fields":{"type":"array","items":{"type":"string"}},"conflicts":{"type":"array","items":{"$ref":"#/components/schemas/QuoteIssue"}},"allowed_next_actions":{"type":"array","items":{"type":"string","enum":["clarify","generate","prepare","refresh_quote"]}},"generation_allowed":{"type":"boolean"},"confirmation_policy":{"const":"host_required_controls_and_user_scope"},"confirmation_required":{"const":false},"side_effects":{"$ref":"#/components/schemas/QuoteSideEffects"},"validated":{"$ref":"#/components/schemas/QuoteValidated"}}},"Quote":{"type":"object","additionalProperties":false,"required":["currency","total_credits","max_credits","line_items","expires_at","reservation","pricing_source"],"properties":{"currency":{"const":"credits"},"total_credits":{"type":"integer","minimum":0},"max_credits":{"type":"integer","minimum":0},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLineItem"}},"expires_at":{"const":null},"reservation":{"const":"none"},"pricing_source":{"const":"partner_api_credit_costs"}}},"QuoteLineItem":{"type":"object","additionalProperties":false,"required":["operation","credits","scope"],"properties":{"operation":{"type":"string"},"credits":{"type":"integer","minimum":0},"scope":{"$ref":"#/components/schemas/PartnerApiScope"},"reason":{"type":"string"}}},"QuoteAuthorization":{"type":"object","additionalProperties":false,"required":["scope","authorized","entitlement","credit_check","reservation","approval"],"properties":{"scope":{"$ref":"#/components/schemas/PartnerApiScope"},"authorized":{"const":true},"entitlement":{"const":"validated"},"credit_check":{"const":"not_performed"},"reservation":{"const":"none"},"approval":{"const":"not_granted"}}},"QuoteIssue":{"type":"object","additionalProperties":false,"required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}},"QuoteSideEffects":{"type":"object","additionalProperties":false,"required":["provider_called","credits_reserved","credits_debited","approval_recorded"],"properties":{"provider_called":{"const":false},"credits_reserved":{"const":false},"credits_debited":{"const":false},"approval_recorded":{"const":false}}},"QuoteValidated":{"type":"object","additionalProperties":false,"properties":{"output_language":{"type":"string","enum":["ar","en"],"description":"Present only when the caller supplied an explicit output language; quote validation never chooses one."},"dialect":{"type":["string","null"]},"deliverables":{"type":"array","items":{"type":"string"}},"source_ids":{"type":"array","items":{"type":"string"}},"brand_profile_id":{"type":["string","null"]},"preparation_status":{"type":"string","enum":["ready","missing","pending","failed"]}}},"PartnerApiScope":{"type":"string","enum":["copy:write","images:write","speech:write","campaigns:write","templates:write","usage:read","ad-library:read","ad-library:write","context:read","brands:read"]},"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":["1K","2K","512"],"default":"1K","description":"Normalized output resolution tier. Use 1K or 2K. Each image costs 5 credits at 1K and 8 credits at 2K. 512 is deprecated: it remains accepted for older integrations, is rendered and charged at 1K, and new responses report 1K. Responses replayed from before this change may still report 512. 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","voiceover_female","instructional_female","podcast_female","storyteller_female","professional_female"],"default":"confident_announcer","description":"Recommended Lahjty Composer voice persona. Omit voice when using this field; select dialect separately."},"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","saved_to"],"properties":{"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/GenerationUsage"},"saved_to":{"const":"api_request","description":"The generated response and any durable media are retained on the API request record for 30 days; this marker does not mean a user History row was created."}}},"GenerationUsage":{"type":"object","required":["credits_used","balance_after"],"properties":{"credits_used":{"type":"number","minimum":0,"description":"Credits consumed after any partial child refund. For a completed generation this equals the gross generation charge."},"balance_after":{"type":"number","minimum":0,"description":"Account balance after the debit and any settled partial refund."}}},"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":["count","max_characters","framework","audience","target_audience","tone","call_to_action","brand_profile_id"],"properties":{"count":{"type":"integer","minimum":1,"maximum":3},"max_characters":{"type":["integer","null"],"minimum":1,"maximum":4000},"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]},"copy_verified":{"type":"boolean","description":"True when the rendered text was read back and matched content exactly and no watermark was drawn over it afterwards. An image with a deterministic logo overlay is read again after the logo is drawn and is true only when its text still matches; otherwise it is delivered with false. When it does not match, the image is rendered once more with a correction; if it still does not match, the request fails with 422 content_rejected (errors.reason ad_copy_mismatch), is refunded and saves no image."}}},"quality_policy":{"type":"object","required":["ad_checked","checks"],"properties":{"ad_checked":{"type":"boolean","description":"True when the whole finished image passed Lahjty's visual check before delivery and no watermark was drawn over it afterwards: the product matches the supplied product photos, a logo the model drew is intact, people have natural hands and faces, nothing important is cut off, and advertising text is readable (for a text-free image, no stray writing was added). A confirmed problem renders the image once more with a correction; if it persists, the request fails with 422 content_rejected (errors.reason ad_check_failed, errors.issues listing the problem categories), is refunded and saves no image. False when the check could not run and on watermarked images. A deterministic logo overlay is placed after the check, in a slot kept clear for it."},"checks":{"type":"array","items":{"type":"string","enum":["product","logo","anatomy","cut_off","unreadable_text","stray_text","visual_defect"]},"description":"The checks the delivered image passed; empty when ad_checked is false. product appears only when product photos were supplied, logo only for a logo the model drew."}}},"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"}]},"ImageEditRequest":{"description":"Either an edit with an instruction (ImageEditInstructionRequest) or another size of the same ad (ImageResizeRequest). A resize takes no instruction, reference_storage_ids, logo_storage_id, logo_mode or output_language.","oneOf":[{"$ref":"#/components/schemas/ImageEditInstructionRequest"},{"$ref":"#/components/schemas/ImageResizeRequest"}]},"ImageEditInstructionRequest":{"type":"object","additionalProperties":false,"required":["source_request_id","instruction"],"properties":{"source_request_id":{"type":"string","pattern":"^req_[A-Za-z0-9_-]{1,196}$","description":"request_id of an earlier completed image generation, image edit, Ad Library generation, or campaign with a completed image, owned by the calling account."},"instruction":{"type":"string","minLength":3,"maxLength":1000,"description":"The change to make, in Arabic or English. Everything it does not mention is preserved. It is printed only when it explicitly asks for specific words to appear."},"resize":{"type":"boolean","const":false,"description":"Optional. false marks an edit explicitly; an edit always needs an instruction."},"reference_storage_ids":{"type":"array","maxItems":2,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100},"description":"Owned product or subject photos imported with role reference, for example to place a different product. Separate from the logo."},"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":"As for image generations: defaults to model when a logo is supplied, otherwise none. model and overlay require logo_storage_id. A supplied logo replaces an Ad Library overlay by editing its logo-free original. Overlay is skipped for accounts without paid access."},"output_language":{"type":"string","enum":["ar","en"],"description":"Language for text the edit adds or changes. Defaults to the source result's language when known. Existing text keeps its language unless the instruction asks to translate it."},"aspect_ratio":{"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"],"description":"Defaults to the source canvas. A different ratio recomposes the scene instead of stretching it."},"resolution":{"type":"string","enum":["1K","2K","512"],"description":"Defaults to the source resolution, or 1K when unknown. 512 is deprecated and rendered at 1K. The edit is charged at the rendered resolution: 5 credits at 1K, 8 credits at 2K."},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ImageResizeRequest":{"type":"object","additionalProperties":false,"required":["source_request_id","aspect_ratio"],"properties":{"source_request_id":{"type":"string","pattern":"^req_[A-Za-z0-9_-]{1,196}$","description":"request_id of an earlier completed image generation, image edit, Ad Library generation, or campaign with a completed image, owned by the calling account."},"resize":{"type":"boolean","const":true,"description":"true makes the same ad in another size and changes nothing else; the new size is checked like a new image. A request without an instruction is a resize even when resize is omitted."},"aspect_ratio":{"type":"string","enum":["4:5","1:1","9:16"],"description":"The new size: 4:5 feed post, 1:1 square or 9:16 Story. It must differ from the source's own size, which otherwise returns 422 invalid_request before any charge."},"resolution":{"type":"string","enum":["1K","2K","512"],"description":"Defaults to the source resolution, or 1K when unknown. 512 is deprecated and rendered at 1K. The edit is charged at the rendered resolution: 5 credits at 1K, 8 credits at 2K."},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ImageEditResult":{"type":"object","required":["id","object","external_id","external_customer_id","metadata","status","output_language","direction","image","watermarked","aspect_ratio","resolution","instruction","reference_images_used","logo_policy","text_policy","edit_of","engine_version"],"properties":{"id":{"type":"string","pattern":"^img_"},"object":{"const":"image_generation","description":"Edits reuse the image_generation object so image consumers need no new shape; edit_of identifies the source."},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"const":"completed"},"output_language":{"type":["string","null"],"enum":["ar","en",null]},"direction":{"type":"string","enum":["rtl","ltr"]},"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"}}},"watermarked":{"type":"boolean"},"aspect_ratio":{"type":"string"},"resolution":{"type":"string","enum":["1K","2K"]},"instruction":{"type":["string","null"],"description":"The edit's instruction; null for a resize."},"resize":{"type":"boolean","description":"True when this result is another size of the source ad, made and checked as a resize. Absent on replays of edits saved before resizes were added, which were all edits."},"reference_images_used":{"type":"integer","minimum":0,"maximum":2},"logo_policy":{"type":"object","required":["mode","logo_overlaid","logo_sent_to_model","logo_storage_id"],"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"]}}},"text_policy":{"type":"object","required":["mode","language","deterministic","renderer","copy_verified"],"properties":{"mode":{"type":"string","enum":["model","none"],"description":"none only for a resize of a text-free ad."},"content":{"type":["string","null"],"description":"For a resize, the source's verified words (one line per text element) that the new size was checked against; null when they were read from the source image, and for an edit. Absent on replays of edits saved before resizes were added."},"language":{"type":["string","null"],"enum":["ar","en",null]},"deterministic":{"const":false},"renderer":{"type":["string","null"],"enum":["image_model",null]},"copy_verified":{"type":"boolean","description":"Edited text is rendered by the image model and is not verified, so an edit reports false; review it. A resize reports true when its text was read back and matched the source's words exactly and no watermark was drawn over it afterwards."}}},"quality_policy":{"type":"object","description":"Absent on replays of edits saved before resizes were added, which were not checked.","required":["ad_checked","checks"],"properties":{"ad_checked":{"type":"boolean","description":"True when a resize passed Lahjty's visual check before delivery and no watermark was drawn over it afterwards: the product matches the source image, people have natural hands and faces, nothing important is cut off, and advertising text is readable (for a text-free ad, no stray writing was added). False for an edit, on watermarked images and when the check could not run."},"checks":{"type":"array","items":{"type":"string","enum":["product","logo","anatomy","cut_off","unreadable_text","stray_text","visual_defect"]},"description":"The checks the delivered image passed; empty when ad_checked is false. product appears only when the source itself was checked against the supplied product photos."}}},"edit_of":{"type":"object","required":["request_id","image_id","operation","used_logo_free_original"],"properties":{"request_id":{"type":"string"},"image_id":{"type":"string","pattern":"^img_"},"operation":{"type":"string","enum":["image.generate","image.edit","ad_library.generate","campaign.generate"]},"used_logo_free_original":{"type":"boolean","description":"True when a supplied logo replaced an Ad Library overlay, so its logo-free original was edited."}}},"engine_version":{"type":"string"}}},"ImageEditResponse":{"allOf":[{"$ref":"#/components/schemas/ImageEditResult"},{"$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"]},"voice_source":{"type":"string","enum":["designed","prebuilt"],"description":"Present on new speech results; absent from historical idempotent replays. Indicates whether a project-owned designed voice or a prebuilt provider voice spoke the audio. A designed voice is never replaced by a prebuilt voice."},"delivery":{"$ref":"#/components/schemas/SpeechDelivery"},"content_type":{"$ref":"#/components/schemas/SpeechContentType"},"prompt_context_source":{"type":"string","enum":["optimized","fallback","provider_voice"],"description":"optimized includes deterministic Gemini 3.8 speech style setup; it does not imply a separate model call."},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"dialect":{"type":["string","null"],"description":"Arabic dialect or null for English."},"provider":{"type":"string","enum":["openrouter","google-ai-studio","google-vertex"],"description":"Endpoint that produced the audio. New results use openrouter or google-ai-studio, both running the same Gemini speech model; google-vertex appears only on historical idempotent replays. Treat unknown values as informational."},"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","partial","saved_to","external_id","external_customer_id","metadata","output_language","market","dialect","dialect_source","copy","whatsapp_template","image","speech","deliverables","engine_version"],"properties":{"id":{"type":"string","pattern":"^cmp_"},"object":{"const":"campaign"},"status":{"const":"completed"},"partial":{"const":false},"saved_to":{"const":"api_request","description":"The response is retained on the API request record for 30 days."},"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"}]},"deliverables":{"$ref":"#/components/schemas/CampaignDeliverables"},"engine_version":{"type":"string"}}}]},"CampaignPartialResponse":{"allOf":[{"$ref":"#/components/schemas/GenerationEnvelope"},{"type":"object","required":["id","object","status","partial","saved_to","external_id","external_customer_id","metadata","output_language","market","dialect","dialect_source","copy","whatsapp_template","image","speech","deliverables","credits_refunded","refund_pending","engine_version"],"properties":{"id":{"type":"string","pattern":"^cmp_"},"object":{"const":"campaign"},"status":{"const":"partial"},"partial":{"const":true},"saved_to":{"const":"api_request","description":"The partial response and successful child media are retained on the API request record for 30 days."},"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"}]},"deliverables":{"$ref":"#/components/schemas/CampaignDeliverables"},"credits_refunded":{"type":"integer","minimum":1,"description":"Credits returned for the failed image and/or speech child deliverable."},"refund_pending":{"const":false,"description":"A successful 207 response has completed the partial refund. A pending refund is represented by a retryable problem response and the stored request record."},"engine_version":{"type":"string"}}}]},"CampaignDeliverables":{"type":"object","additionalProperties":false,"required":["copy","image","speech"],"properties":{"copy":{"$ref":"#/components/schemas/CampaignDeliverable"},"image":{"$ref":"#/components/schemas/CampaignDeliverable"},"speech":{"$ref":"#/components/schemas/CampaignDeliverable"}}},"CampaignDeliverable":{"type":"object","additionalProperties":false,"required":["enabled","status","credits"],"properties":{"enabled":{"type":"boolean"},"status":{"type":"string","enum":["completed","failed","disabled"]},"id":{"type":"string","pattern":"^(cpy_|img_|spc_)"},"credits":{"type":"integer","minimum":0},"error":{"oneOf":[{"$ref":"#/components/schemas/CampaignDeliverableError"},{"type":"null"}]}}},"CampaignDeliverableError":{"type":"object","additionalProperties":false,"required":["component","code","message","retryable"],"properties":{"component":{"type":"string","enum":["image","speech"]},"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}},"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":{"$ref":"#/components/schemas/ProblemErrors"}}},"ProblemErrors":{"description":"Structured validation, scope, or reconciliation metadata. Validation failures use path/message entries; scope failures may include required_scope; partial refund recovery may include refund_credits.","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/ProblemFieldError"}},{"type":"object","additionalProperties":true,"properties":{"reason":{"type":"string"},"required_scope":{"$ref":"#/components/schemas/PartnerApiScope"},"refund_credits":{"type":"integer","minimum":1}}},{"type":"string"}]},"ProblemFieldError":{"type":"object","additionalProperties":false,"required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}},"ApiUsageAttempt":{"type":"object","required":["id","operation","status","credits","net_credits","partial_refund_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},"net_credits":{"type":"integer","minimum":0,"description":"Credits retained after any partial child refund. This is zero for a fully refunded failed attempt."},"partial_refund_credits":{"type":"integer","minimum":0,"description":"Credits returned for failed child deliverables of an otherwise successful request."},"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","net_credits","partial_refund_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},"net_credits":{"type":"integer","minimum":0,"description":"Credits retained after any partial child refund. This is zero for a fully refunded failed attempt."},"partial_refund_credits":{"type":"integer","minimum":0,"description":"Credits returned for failed child deliverables of an otherwise successful request."},"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","net_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. This legacy summary remains gross and is not reduced by partial child refunds or later template outcome refunds."},"net_credits_used":{"type":"number","minimum":0,"description":"Successful generation credits after subtracting recorded partial child refunds in the same latest-50 summary window."},"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"}}}}}}}