{"openapi":"3.1.0","info":{"title":"Lahjty API","version":"2026-09-19","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 ad ID in q) returns only that ad or 404. Invalid industry/sector/style values return 422; use the enumerated values or omit the filter.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"id","schema":{"type":"string","maxLength":100}},{"in":"query","name":"q","schema":{"type":"string","maxLength":200}},{"in":"query","name":"brief","schema":{"type":"string","maxLength":2000}},{"in":"query","name":"locale","schema":{"type":"string","enum":["en","ar"]}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":30,"default":10}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"maximum":10000}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"maximum":99}},{"in":"query","name":"industry","schema":{"type":"string","enum":["SaaS & Cloud Software","AI Tools","E-commerce & Physical Products","Mobile Apps & Games","Finance & FinTech","Health, Fitness & Wellness","Beauty & Skincare","Food & Beverage","Info-Products & Courses","Professional B2B Services","Local & Home Services","Travel & Hospitality","Automotive","Other / General"]}},{"in":"query","name":"sector","schema":{"type":"string","enum":["all","saas","ai","ecommerce","apps","fintech","health","beauty","food","education","b2b","local","travel","automotive","general"]}},{"in":"query","name":"style","schema":{"type":"string","enum":["all","product","offer","launch","proof","problem","comparison","educational","story","hook"]}}],"responses":{"200":{"description":"Catalog items with match rationale and next page/offset","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/{id}":{"get":{"operationId":"getAdLibraryItem","summary":"Inspect an ad, editable fields, reference requirements and preparation state","description":"Requires ad-library:read. Read-only, no analysis or generation charge.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"schema":{"default":"en","enum":["en","ar"],"type":"string"},"name":"locale","in":"query"}],"responses":{"200":{"description":"Ad and available generation contract","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/{id}/prepare":{"post":{"operationId":"prepareAdLibraryItem","summary":"Explicitly prepare an ad's editable contract","description":"Requires ad-library:write. Missing analysis costs one credit; an already prepared contract costs zero. The shared analysis ledger owns debit and refund recovery. usage.credits_used reports this analysis charge; balance_after is null. Read detail after a pending/uncertain result. Reuse the exact body and Idempotency-Key on retry. Pending 409 and allowance 429 are retryable with that same key; wait for completion or the stated reset time. Each failed attempt remains inspectable.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"locale":{"type":"string","enum":["en","ar"],"default":"en"}}},"examples":{"prepare":{"value":{"locale":"ar"}}}}}},"responses":{"200":{"description":"Prepared contract and actual analysis charge","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/{id}/generations":{"post":{"operationId":"generateAdLibraryImage","summary":"Generate a saved ad from approved editable fields and owned images","description":"Requires images:write. Charges the image credit cost. Saves the image in History. With logo_mode overlay, also preserves the clean original and editable logo composition; model-rendered branding is part of the artwork. A supplied logo defaults to model mode; none ignores it. Preparation is explicit and never runs automatically. Saved snippet and terminal request complete atomically.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdLibraryGenerationRequest"},"examples":{"arabic":{"value":{"reference_storage_ids":["owned_storage_id"],"template_fields":{"headline":"قهوة مختصة","cta":"اطلب الآن"},"aspect_ratio":"1:1","locale":"ar"}}}}}},"responses":{"201":{"description":"Private image, original image, saved snippet ID, logo policy and usage","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/ad-library/uploads":{"post":{"operationId":"uploadAdLibraryImage","summary":"Import an HTTPS attachment as an owned temporary reference or logo","description":"Requires ad-library:write. No credits. DNS-pinned download rejects private networks and Lahjty/Convex media URLs, including redirects. Use existing owned storage IDs directly. Non-animated PNG/JPEG/WebP, max 5 MB; reference max 16 megapixels; logo limits follow Brand Profile policy. Unattached uploads expire in 24 hours.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","maxLength":4000},"role":{"type":"string","enum":["reference","logo"],"default":"reference"}}},"examples":{"reference":{"value":{"role":"reference","url":"https://attachments.example/product.png"}}}}}},"responses":{"201":{"description":"Owned storage_id and upload metadata","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}},"delete":{"operationId":"discardAdLibraryUpload","summary":"Discard an owned unattached reference or logo","description":"Requires ad-library:write. Attached and foreign-account files cannot be discarded.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":100},"required":true,"in":"query","name":"storage_id"}],"responses":{"200":{"description":"Deletion outcome","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"}}}},"/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.","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","security":[],"responses":{"200":{"description":"Current capabilities","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Problem"}}}},"/copy-generations":{"post":{"operationId":"createCopyGeneration","tags":["Generation"],"summary":"Generate Arabic or English copy, or convert Arabic dialect","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyGenerationRequest"},"examples":{"arabicWhatsapp":{"summary":"Saudi WhatsApp AIDA copy with enforced keyword rules","value":{"type":"ad_copy","description":"Weekend offer: 20% off specialty coffee subscriptions","output_language":"ar","market":"SA","dialect":"saudi","platform":"whatsapp","tone":"warm","framework":"aida","audience":"specific","specific_audience":"Young professionals in Riyadh","keywords":["نهاية الأسبوع"],"required_keywords":["قهوة مختصة"],"excluded_keywords":["مجاني"],"call_to_action":"اطلب الآن"}},"englishCopy":{"summary":"English copy with UAE market context and no dialect","value":{"type":"ad_copy","description":"Same-day flower delivery launch offer","output_language":"en","market":"AE","platform":"instagram","tone":"warm","framework":"pas","call_to_action":"Order today"}},"iraqiConversion":{"summary":"Convert approved Saudi Arabic copy to Iraqi Arabic","value":{"type":"dialect_conversion","description":"قهوتك المفضلة توصلك لين باب البيت. اطلب الآن.","output_language":"ar","market":"IQ","source_dialect":"saudi","target_dialect":"iraqi","platform":"whatsapp"}}}}}},"responses":{"201":{"description":"Copy generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyGenerationResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/image-generations":{"post":{"operationId":"createImageGeneration","tags":["Generation"],"summary":"Generate and durably host a campaign image","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"},"examples":{"textFree":{"summary":"Text-free product showcase","value":{"prompt":"Premium specialty coffee weekend campaign","type":"product_showcase","style":"photorealistic","aspect_ratio":"1:1","resolution":"1K","visual_keywords":["coffee beans","Saudi coffee cup"],"excluded_visuals":["people","logos"],"include_text":false}},"arabicModelText":{"summary":"2K offer announcement with Arabic text rendered by the model","value":{"prompt":"Premium specialty coffee weekend campaign","type":"offer_announcement","aspect_ratio":"1:1","resolution":"2K","include_text":true,"overlay_text":"قهوتك، بطابعك","overlay_text_language":"ar"}},"englishModelText":{"summary":"Lifestyle image with English text rendered by the model","value":{"prompt":"Premium specialty coffee weekend campaign","type":"lifestyle","resolution":"1K","include_text":true,"overlay_text":"Weekend coffee offer","overlay_text_language":"en"}}}}}},"responses":{"201":{"description":"Image generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}}}},"/speech-generations":{"post":{"operationId":"createSpeechGeneration","tags":["Generation"],"summary":"Generate and durably host Arabic or English speech","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechGenerationRequest"},"examples":{"whatsappVoice":{"summary":"Gulf Arabic WhatsApp voice asset","value":{"text":"طلبك صار جاهز، ونوصله لك بكرة بإذن الله.","dialect":"gulf","tone":"warm","platform":"whatsapp","delivery":"natural","content_type":"marketing","voice_profile":"warm_storyteller","external_customer_id":"merchant-91"}},"english":{"summary":"English transcript without Arabic dialect","value":{"text":"Your order is ready for delivery.","output_language":"en","delivery":"natural","voice_profile":"warm_storyteller"}}}}}},"responses":{"201":{"description":"Speech generated","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechGenerationResponse"}}}},"4XX":{"$ref":"#/components/responses/Problem"},"5XX":{"$ref":"#/components/responses/Problem"}},"description":"Read the approved Arabic or English transcript exactly. output_language defaults to ar; Arabic dialect defaults to saudi. English must omit dialect. Costs 5 credits."}},"/campaigns":{"post":{"operationId":"createCampaign","tags":["Generation"],"summary":"Generate copy, optional image, optional speech, and a WhatsApp draft","description":"The cost is calculated from enabled deliverables. Copy is always included. Independent image and speech generation run in parallel after copy is ready. 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-09-19"}}},"responses":{"Problem":{"description":"RFC 9457 problem response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Lahjty-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"AdLibraryGenerationRequest":{"type":"object","required":["template_fields"],"additionalProperties":false,"properties":{"template_fields":{"type":"object","additionalProperties":{"type":"string","maxLength":4000},"description":"Exact approved values keyed by IDs from the prepared contract; each field's contract limit also applies."},"locale":{"type":"string","enum":["en","ar"],"default":"ar"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"],"default":"1:1"},"reference_storage_ids":{"type":"array","maxItems":2,"items":{"type":"string","maxLength":100}},"logo_storage_id":{"type":"string","maxLength":100},"logo_mode":{"type":"string","enum":["model","overlay","none"],"description":"Defaults to model when a logo is supplied, otherwise none. model sends the real logo as a separate image-model reference; overlay composites it deterministically; none ignores a supplied logo. model and overlay require logo_storage_id."},"palette":{"type":"object","additionalProperties":false,"properties":{"primary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}}}}},"CopyGenerationRequest":{"type":"object","additionalProperties":false,"required":["description"],"properties":{"type":{"type":"string","enum":["ad_copy","headlines","dialect_conversion"],"default":"ad_copy"},"description":{"type":"string","minLength":1,"maxLength":8000},"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"]},"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"]},"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":["512","1K","2K"],"default":"1K","description":"Normalized output resolution tier sent to the image provider. Actual pixel width and height are returned in image.width and image.height."},"OverlayTextLanguage":{"type":"string","enum":["auto","ar","en"],"default":"auto","description":"auto preserves the supplied phrase and detects its script. ar or en translates a mismatched source phrase before including it in the Composer image prompt."},"KeywordList":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":80}},"VisualList":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":120}},"SpeechDelivery":{"type":"string","enum":["auto","natural","reel_voiceover","conversational","professional","energetic","storytelling"],"default":"natural"},"SpeechContentType":{"type":"string","enum":["marketing","general"],"default":"marketing"},"VoiceProfile":{"type":"string","enum":["bright_presenter","warm_storyteller","confident_announcer","modern_narrator","premium_narrator","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]}}},"visual_policy":{"type":"object","required":["required","excluded"],"properties":{"required":{"$ref":"#/components/schemas/VisualList"},"excluded":{"$ref":"#/components/schemas/VisualList"}}},"prompt_plan":{"type":"object","required":["prompt","composition","typography","culturalNotes","negativePrompt"],"properties":{"prompt":{"type":"string"},"composition":{"type":["string","null"]},"typography":{"type":["string","null"]},"culturalNotes":{"type":["string","null"]},"negativePrompt":{"type":["string","null"]}}},"engine_version":{"type":"string"}}},"ImageGenerationResponse":{"allOf":[{"$ref":"#/components/schemas/ImageResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"SpeechResult":{"type":"object","required":["id","object","external_id","external_customer_id","metadata","status","audio","voice","voice_profile","delivery","content_type","prompt_context_source","output_language","dialect","provider","fallback_used","engine_version"],"properties":{"id":{"type":"string","pattern":"^spc_"},"object":{"const":"speech_generation"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"const":"completed"},"audio":{"type":"object","required":["url","mime_type","bytes","duration_seconds"],"properties":{"url":{"type":"string","format":"uri"},"mime_type":{"type":"string"},"bytes":{"type":"integer"},"duration_seconds":{"type":["number","null"]}}},"voice":{"$ref":"#/components/schemas/Voice"},"voice_profile":{"type":["string","null"]},"voice_source":{"type":"string","enum":["designed","prebuilt"],"description":"Present on new speech results; absent from historical idempotent replays. Indicates whether AI Studio used a project-owned Voice Design or a prebuilt provider voice. Vertex fallback always uses prebuilt."},"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":["google-ai-studio","google-vertex"]},"fallback_used":{"type":"boolean"},"engine_version":{"type":"string"}}},"SpeechGenerationResponse":{"allOf":[{"$ref":"#/components/schemas/SpeechResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"WhatsAppTemplateCategory":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"WhatsAppTemplateDraftRequest":{"type":"object","additionalProperties":false,"required":["name","category","purpose"],"properties":{"name":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-z0-9_]+$"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"language_code":{"type":"string","enum":["ar","en","en_GB","en_US"],"description":"Supported Meta template locale code. It must match output_language and defaults to ar or en. Market affects generation context, not this code."},"market":{"$ref":"#/components/schemas/Market"},"dialect":{"$ref":"#/components/schemas/CopyDialect"},"purpose":{"type":"string","minLength":10,"maxLength":2000},"customer_action_context":{"type":"string","minLength":5,"maxLength":1000,"description":"Required for UTILITY; describe the specific user-initiated transaction or request."},"opt_in_context":{"type":"string","minLength":5,"maxLength":1000,"description":"Required for MARKETING; describe how recipients consented to these messages."},"variables":{"type":"array","maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["name","example"],"properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"},"example":{"type":"string","minLength":1,"maxLength":500}}}},"header":{"type":"string","enum":["NONE","TEXT"],"default":"NONE"},"footer":{"type":"boolean","default":false},"buttons":{"type":"array","maxItems":3,"items":{"oneOf":[{"$ref":"#/components/schemas/WhatsAppQuickReplyButton"},{"$ref":"#/components/schemas/WhatsAppUrlButton"},{"$ref":"#/components/schemas/WhatsAppPhoneButton"}]}},"authentication":{"type":"object","additionalProperties":false,"properties":{"add_security_recommendation":{"type":"boolean","default":true},"code_expiration_minutes":{"type":"integer","minimum":1,"maximum":90,"default":10}}},"external_id":{"type":"string","maxLength":200},"external_customer_id":{"type":"string","maxLength":200},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"WhatsAppQuickReplyButton":{"type":"object","additionalProperties":false,"required":["type","text"],"properties":{"type":{"const":"QUICK_REPLY"},"text":{"type":"string","minLength":1,"maxLength":25}}},"WhatsAppUrlButton":{"type":"object","additionalProperties":false,"required":["type","text","url"],"properties":{"type":{"const":"URL"},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","format":"uri","maxLength":2000}}},"WhatsAppPhoneButton":{"type":"object","additionalProperties":false,"required":["type","text","phone_number"],"properties":{"type":{"const":"PHONE_NUMBER"},"text":{"type":"string","minLength":1,"maxLength":25},"phone_number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}}},"WhatsAppTemplateDraftResult":{"type":"object","required":["id","object","status","external_id","external_customer_id","metadata","output_language","market","dialect","dialect_source","meta_payload","payload_hash","compliance","provider_usage"],"properties":{"id":{"type":"string","pattern":"^wtd_"},"object":{"const":"whatsapp_template_draft"},"status":{"const":"UNSUBMITTED"},"external_id":{"type":["string","null"]},"external_customer_id":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"output_language":{"$ref":"#/components/schemas/OutputLanguage"},"market":{"type":["string","null"]},"dialect":{"oneOf":[{"$ref":"#/components/schemas/CopyDialect"},{"type":"null"}]},"dialect_source":{"type":["string","null"],"enum":["explicit","market","fallback",null]},"meta_payload":{"type":"object","required":["name","language","category","components"],"properties":{"name":{"type":"string"},"language":{"type":"string"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"components":{"type":"array","items":{"type":"object"}}}},"payload_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"compliance":{"type":"object","required":["ready_for_submission","findings","final_decision_owner"],"properties":{"ready_for_submission":{"const":true},"findings":{"type":"array","items":{"type":"object"}},"final_decision_owner":{"const":"META"}}},"provider_usage":{"type":"object"}}},"WhatsAppTemplateDraftResponse":{"allOf":[{"$ref":"#/components/schemas/WhatsAppTemplateDraftResult"},{"$ref":"#/components/schemas/GenerationEnvelope"}]},"WhatsAppTemplateOutcomeRequest":{"type":"object","additionalProperties":false,"required":["outcome","meta_template_id","provider_event_id","submitted_payload_hash"],"properties":{"outcome":{"type":"string","enum":["SUBMITTED","APPROVED","REJECTED","RECLASSIFIED","PAUSED","DISABLED"]},"meta_template_id":{"type":"string","maxLength":200},"provider_event_id":{"type":"string","maxLength":200,"description":"Partner-supplied correlation and deduplication identifier. It is not accepted as proof of a Meta outcome."},"submitted_payload_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"reason":{"type":"string","maxLength":2000},"occurred_at":{"type":"string","format":"date-time"}}},"WhatsAppTemplateOutcomeResponse":{"allOf":[{"$ref":"#/components/schemas/GenerationEnvelope"},{"type":"object","required":["object","draft_id","outcome","unchanged","category","refund"],"properties":{"object":{"const":"whatsapp_template_outcome"},"draft_id":{"type":"string"},"outcome":{"type":"string"},"unchanged":{"type":"boolean"},"category":{"$ref":"#/components/schemas/WhatsAppTemplateCategory"},"refund":{"type":"object","required":["candidate","eligible","status","credits","balance_after","verification_required"],"properties":{"candidate":{"type":"boolean","description":"True when the reported outcome is REJECTED and the submitted hash matches the generated draft. A candidate is not yet eligible for credit until evidence is verified."},"eligible":{"type":"boolean"},"status":{"type":"string","enum":["NOT_ELIGIBLE","PENDING_VERIFICATION","REFUNDED"]},"credits":{"type":"number"},"balance_after":{"type":["number","null"]},"verification_required":{"type":"boolean"}}}}}]},"WhatsAppTemplateDraft":{"type":"object","required":["status","header","body","footer","buttons","warnings"],"properties":{"status":{"const":"draft"},"header":{"type":["string","null"]},"body":{"type":"string"},"footer":{"type":["string","null"]},"buttons":{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"const":"quick_reply"},"text":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"}}}},"CampaignResponse":{"allOf":[{"$ref":"#/components/schemas/GenerationEnvelope"},{"type":"object","required":["id","object","status","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"}}}}}}}