{"openapi":"3.0.3","info":{"title":"Unlimited TTS API","version":"2","description":"Paid text-to-speech gateway with prepaid card-credit and direct x402 payment flows."},"servers":[{"url":"/","description":"The same origin that served this document."}],"externalDocs":{"description":"Agent payment-flow and operational guide.","url":"/docs"},"tags":[{"name":"Service","description":"Service metadata."},{"name":"Documentation","description":"Machine-readable documentation endpoints."},{"name":"TTS","description":"Text-to-speech operations."},{"name":"TTS jobs","description":"Asynchronous TTS job polling and audio retrieval."},{"name":"Card credits","description":"Prepaid Stripe-funded credit accounts."},{"name":"x402","description":"Direct x402 USDC machine payments."},{"name":"x402 prepaid","description":"Signature-authenticated prepaid USDC balances that remove facilitator and settlement latency from each request."}],"components":{"schemas":{"Health":{"type":"object","properties":{"service":{"type":"string","enum":["unlimited-tts"]},"status":{"type":"string","enum":["ok"]},"documentation":{"type":"string"},"openapi":{"type":"string"},"endpoints":{"type":"array","items":{"type":"string"}}},"required":["service","status","documentation","openapi","endpoints"]},"LegacyAgentGuide":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"documentation":{"type":"string"},"openapi":{"type":"object","properties":{"version":{"type":"string","enum":["3.0.3"]},"url":{"type":"string"},"status":{"type":"string","enum":["canonical"]}},"required":["version","url","status"]},"limits":{"type":"object","properties":{},"additionalProperties":{"nullable":true}},"payment":{"type":"object","properties":{},"additionalProperties":{"nullable":true}},"endpoints":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}},"errorCodes":{"type":"array","items":{"type":"string"}},"agentGuide":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}},"required":["service","version","description","documentation","openapi","limits","payment","endpoints","errorCodes","agentGuide"]},"SignedX402ServiceMetadata":{"type":"object","properties":{"payload":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1"]},"service":{"type":"object","properties":{"name":{"type":"string","enum":["Unlimited TTS"]},"origin":{"type":"string","format":"uri"},"metadataUrl":{"type":"string","format":"uri"}},"required":["name","origin","metadataUrl"]},"protocol":{"type":"object","properties":{"name":{"type":"string","enum":["x402"]},"version":{"type":"number","enum":[2]},"scheme":{"type":"string","enum":["exact"]}},"required":["name","version","scheme"]},"payment":{"type":"object","properties":{"network":{"type":"string"},"asset":{"type":"object","properties":{"address":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"decimals":{"type":"integer","minimum":0}},"required":["address","symbol","name","decimals"]},"payees":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"status":{"type":"string","enum":["current","next","retiring"]},"validFrom":{"type":"string","format":"date-time"},"validUntil":{"type":"string","nullable":true,"format":"date-time"}},"required":["address","status","validFrom","validUntil"]}}},"required":["network","asset","payees"]},"pricing":{"type":"object","properties":{"currency":{"type":"string","enum":["USD"]},"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"billingUnit":{"type":"string","enum":["character"]},"ratePerCharacterUsd":{"type":"string"},"maxCharactersPerRequest":{"type":"integer","minimum":0,"exclusiveMinimum":true},"maxChargeUsd":{"type":"string"}},"required":["id","provider","billingUnit","ratePerCharacterUsd","maxCharactersPerRequest","maxChargeUsd"]}},"quoteEndpoint":{"type":"string","format":"uri"}},"required":["currency","models","quoteEndpoint"]},"validity":{"type":"object","properties":{"issuedAt":{"type":"string","format":"date-time"},"validFrom":{"type":"string","format":"date-time"},"validUntil":{"type":"string","format":"date-time"}},"required":["issuedAt","validFrom","validUntil"]},"trust":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"keyId":{"type":"string"},"algorithm":{"type":"string","enum":["ES256"]},"status":{"type":"string","enum":["current","next","retiring"]},"publicKeyJwk":{"type":"object","properties":{"kty":{"type":"string","enum":["EC"]},"crv":{"type":"string","enum":["P-256"]},"x":{"type":"string"},"y":{"type":"string"},"alg":{"type":"string","enum":["ES256"]},"key_ops":{"type":"array","items":{"type":"string","enum":["verify"]}},"ext":{"type":"boolean","enum":[true]},"kid":{"type":"string"}},"required":["kty","crv","x","y","alg","key_ops","ext"]},"validFrom":{"type":"string","format":"date-time"},"validUntil":{"type":"string","nullable":true,"format":"date-time"}},"required":["keyId","algorithm","status","publicKeyJwk","validFrom","validUntil"]}},"rotationRule":{"type":"string"},"bootstrapRule":{"type":"string"}},"required":["keys","rotationRule","bootstrapRule"]},"recovery":{"type":"object","properties":{"paymentIdentifierRequired":{"type":"boolean","enum":[true]},"replayWindowSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"chargesFinal":{"type":"boolean","enum":[true]},"refunds":{"type":"string","enum":["none"]},"unknownOutcomeCode":{"type":"string","enum":["PAYMENT_OUTCOME_UNKNOWN"]},"automaticRetryOnUnknownOutcome":{"type":"boolean","enum":[false]}},"required":["paymentIdentifierRequired","replayWindowSeconds","chargesFinal","refunds","unknownOutcomeCode","automaticRetryOnUnknownOutcome"]},"prepaid":{"type":"object","properties":{"supported":{"type":"boolean","enum":[true]},"depositEndpoint":{"type":"string","format":"uri"},"balanceEndpoint":{"type":"string"},"accountIdentity":{"type":"string","enum":["payer_evm_address"]},"authentication":{"type":"object","properties":{"scheme":{"type":"string","enum":["eip712"]},"primaryType":{"type":"string","enum":["PrepaidRequest"]},"domainName":{"type":"string"},"domainVersion":{"type":"string"},"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"headers":{"type":"array","items":{"type":"string"}},"signatureTtlSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"smartAccountSignaturesSupported":{"type":"boolean","enum":[false]}},"required":["scheme","primaryType","domainName","domainVersion","chainId","headers","signatureTtlSeconds","smartAccountSignaturesSupported"]},"minDepositMicroUsd":{"type":"integer","minimum":0,"exclusiveMinimum":true},"maxDepositMicroUsd":{"type":"integer","minimum":0,"exclusiveMinimum":true},"withdrawable":{"type":"boolean","enum":[false],"description":"Deposited funds can be spent on this service but never withdrawn."},"settlementPerRequest":{"type":"boolean","enum":[false]}},"required":["supported","depositEndpoint","balanceEndpoint","accountIdentity","authentication","minDepositMicroUsd","maxDepositMicroUsd","withdrawable","settlementPerRequest"]}},"required":["schemaVersion","service","protocol","payment","pricing","validity","trust","recovery","prepaid"]},"signature":{"type":"object","properties":{"algorithm":{"type":"string","enum":["ES256"]},"keyId":{"type":"string"},"encoding":{"type":"string","enum":["base64url-ieee-p1363"]},"value":{"type":"string"}},"required":["algorithm","keyId","encoding","value"]}},"required":["payload","signature"]},"StructuredError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true,"properties":{},"additionalProperties":{"nullable":true}}},"required":["code","message","details"]}},"required":["error"]},"OpenApiDocument":{"type":"object","properties":{"openapi":{"type":"string","enum":["3.0.3"]},"info":{"type":"object","properties":{"title":{"type":"string"},"version":{"type":"string"}},"required":["title","version"]},"paths":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}},"required":["openapi","info","paths"],"additionalProperties":{"nullable":true}},"TtsJob":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"traceId":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}},"required":["code","message"]},"result":{"type":"object","nullable":true,"properties":{"audioUrl":{"type":"string","nullable":true,"format":"uri"},"stored":{"type":"boolean"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","nullable":true,"minimum":0}},"required":["audioUrl","stored","mimeType","sizeBytes"]},"links":{"type":"object","properties":{"status":{"type":"string","format":"uri"},"audio":{"type":"string","nullable":true,"format":"uri"}},"required":["status","audio"]}},"required":["jobId","status","traceId","createdAt","updatedAt","startedAt","completedAt","error","result","links"]},"TopUpStatus":{"allOf":[{"$ref":"#/components/schemas/CreditAccount"},{"type":"object","properties":{"status":{"type":"string","enum":["active","not_found"]},"links":{"type":"object","properties":{"credits":{"type":"string","format":"uri"}},"required":["credits"]}},"required":["status"]}]},"CreditAccount":{"type":"object","properties":{"accountId":{"type":"string"},"balanceMicroUsd":{"type":"integer","minimum":0},"balanceUsd":{"type":"string"},"currency":{"type":"string"}},"required":["accountId","balanceMicroUsd","balanceUsd","currency"]},"VoicesResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"model":{"type":"string"},"total":{"type":"integer","minimum":0},"pricing":{"$ref":"#/components/schemas/VoicePricing"},"available":{"type":"boolean"},"voices":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}}},"required":["success","model","total","pricing","available","voices"]},"VoicePricing":{"type":"object","properties":{"currency":{"type":"string","enum":["USD"]},"model":{"type":"string"},"billingUnit":{"type":"string","enum":["character"]},"ratePerCharUsd":{"type":"number","minimum":0},"ratePerMillionCharsUsd":{"type":"number","minimum":0},"maxInputCharacters":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["currency","model","billingUnit","ratePerCharUsd","ratePerMillionCharsUsd","maxInputCharacters"]},"Voice":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"voice":{"type":"string"},"model":{"type":"string"},"name":{"type":"string"}},"required":["id","provider","voice","model","name"]},"TtsModelsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"defaultModel":{"type":"string"},"total":{"type":"integer","minimum":0},"models":{"type":"array","items":{"$ref":"#/components/schemas/TtsModel"}}},"required":["success","defaultModel","total","models"]},"TtsModel":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"maxInputCharacters":{"type":"integer","minimum":0,"exclusiveMinimum":true},"defaultVoice":{"type":"string"},"speed":{"type":"object","properties":{"min":{"type":"number","minimum":0,"exclusiveMinimum":true},"max":{"type":"number","minimum":0,"exclusiveMinimum":true},"default":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["min","max","default"]},"pricing":{"$ref":"#/components/schemas/VoicePricing"},"voices":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"available":{"type":"boolean"}},"required":["id","provider","name","description","maxInputCharacters","defaultVoice","speed","pricing","voices","available"]},"TtsRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4096},"model":{"type":"string","minLength":1,"maxLength":100,"description":"Provider-qualified model id from GET /tts/models. Defaults to openai/tts-1."},"voice":{"type":"string","minLength":1,"maxLength":100,"description":"Public provider_voice id, for example openai_nova."},"speed":{"type":"number","minimum":0.5,"maximum":2,"description":"Playback speed."},"storeAudio":{"type":"boolean","description":"Whether an asynchronous result may be retained in R2."}},"required":["text"]},"X402QuoteResponse":{"type":"object","properties":{"quoteId":{"type":"string"},"quoteToken":{"type":"string"},"textLength":{"type":"integer","minimum":0,"exclusiveMinimum":true},"textSha256":{"type":"string"},"model":{"type":"string"},"voice":{"type":"string"},"speed":{"type":"number"},"amountMicroUsd":{"type":"integer","minimum":0,"exclusiveMinimum":true},"amountUsd":{"type":"string"},"network":{"type":"string"},"payTo":{"type":"string"},"issuedAt":{"type":"string"},"expiresAt":{"type":"string"},"paymentEndpoint":{"type":"string","enum":["/x402/tts"]}},"required":["quoteId","quoteToken","textLength","textSha256","model","voice","speed","amountMicroUsd","amountUsd","network","payTo","issuedAt","expiresAt","paymentEndpoint"]},"X402QuoteRequest":{"type":"object","properties":{"textLength":{"type":"integer","minimum":1,"maximum":4096},"textSha256":{"type":"string","pattern":"^[a-fA-F0-9]{64}$"},"model":{"type":"string","minLength":1,"maxLength":100,"description":"Provider-qualified model id. Defaults to openai/tts-1."},"voice":{"type":"string","minLength":1,"maxLength":100},"speed":{"type":"number","minimum":0.5,"maximum":2}},"required":["textLength","textSha256"]},"X402DepositResponse":{"allOf":[{"$ref":"#/components/schemas/X402PrepaidAccount"},{"type":"object","properties":{"creditedMicroUsd":{"type":"integer","minimum":0},"alreadyCredited":{"type":"boolean","description":"True when this settled payment had already been credited and was not double counted."}},"required":["creditedMicroUsd","alreadyCredited"]}]},"X402PrepaidAccount":{"type":"object","properties":{"address":{"type":"string"},"balanceMicroUsd":{"type":"integer","minimum":0},"balanceUsd":{"type":"string"},"currency":{"type":"string"},"refundable":{"type":"boolean","enum":[false],"description":"Prepaid balances are spend-only and cannot be withdrawn."}},"required":["address","balanceMicroUsd","balanceUsd","currency","refundable"]},"X402DepositRequest":{"type":"object","properties":{"amountMicroUsd":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Amount to prepay. One micro-USD is one atomic USDC unit."}},"required":["amountMicroUsd"]},"X402TtsPostBody":{"anyOf":[{"$ref":"#/components/schemas/TtsRequest"},{"$ref":"#/components/schemas/X402QuotedTtsRequest"}]},"X402QuotedTtsRequest":{"type":"object","properties":{"quoteToken":{"type":"string","minLength":1,"maxLength":4096,"description":"Signed token returned by POST /x402/tts/quote."},"text":{"type":"string","minLength":1,"maxLength":4096,"description":"Omit while obtaining PAYMENT-REQUIRED; include on the paid request."},"model":{"type":"string","minLength":1,"maxLength":100},"voice":{"type":"string","minLength":1,"maxLength":100},"speed":{"type":"number","minimum":0.5,"maximum":2}},"required":["quoteToken"]}},"parameters":{}},"paths":{"/":{"get":{"operationId":"getServiceHealth","tags":["Service"],"summary":"Get service health and endpoint links.","responses":{"200":{"description":"The service is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"500":{"description":"Unexpected service failure."}}}},"/docs":{"get":{"operationId":"getAgentGuide","tags":["Documentation"],"summary":"Get the legacy machine-readable payment and agent guide.","description":"This guide is retained for compatibility and workflow guidance. Use /openapi.json as the canonical HTTP contract.","responses":{"200":{"description":"Agent workflow and operational guidance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyAgentGuide"}}}},"500":{"description":"Unexpected service failure."}}}},"/.well-known/x402-service-metadata":{"get":{"operationId":"getSignedX402ServiceMetadata","tags":["Documentation","x402"],"summary":"Get signed x402 network, asset, payee, pricing, and rotation metadata.","description":"Clients must pin a signing key out of band and accept payee or key rotation only when this document verifies under a currently trusted key.","responses":{"200":{"description":"Short-lived signed service metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedX402ServiceMetadata"}}}},"503":{"description":"Metadata signing is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiDocument","tags":["Documentation"],"summary":"Get the canonical OpenAPI 3.0.3 contract.","responses":{"200":{"description":"The generated OpenAPI document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"500":{"description":"The contract could not be generated."}}}},"/tts/jobs/{jobId}":{"get":{"operationId":"getTtsJob","tags":["TTS jobs"],"summary":"Get an asynchronous TTS job.","parameters":[{"schema":{"type":"string","minLength":1,"example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"jobId","in":"path"}],"responses":{"200":{"description":"Current job state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsJob"}}}},"404":{"description":"The job does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Unexpected service or configuration failure."}}}},"/tts/jobs/{jobId}/audio":{"get":{"operationId":"getTtsJobAudio","tags":["TTS jobs"],"summary":"Download audio for a completed asynchronous TTS job.","parameters":[{"schema":{"type":"string","minLength":1,"example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"jobId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":1500,"description":"Signed job token when JOB_SIGNING_SECRET is configured."},"required":false,"description":"Signed job token when JOB_SIGNING_SECRET is configured.","name":"sig","in":"query"}],"responses":{"200":{"description":"Generated speech audio.","headers":{"Content-Disposition":{"description":"Inline audio filename.","schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}}}},"401":{"description":"The audio signature is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"404":{"description":"The job or stored object does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"409":{"description":"The job is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"410":{"description":"The job completed without retaining audio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Unexpected service or configuration failure."}}}},"/top-up":{"get":{"operationId":"getTopUpPage","tags":["Card credits"],"summary":"Open the Stripe Checkout top-up launcher.","parameters":[{"schema":{"type":"string","description":"Requested top-up amount in cents."},"required":false,"description":"Requested top-up amount in cents.","name":"amount","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Existing credit account bearer id."},"required":false,"description":"Existing credit account bearer id.","name":"account","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Payment challenge id carried through Checkout."},"required":false,"description":"Payment challenge id carried through Checkout.","name":"challenge","in":"query"}],"responses":{"200":{"description":"Top-up launcher.","content":{"text/html":{"schema":{"type":"string","description":"HTML rendered by the service."}}}},"500":{"description":"Unexpected service failure."}}},"post":{"operationId":"createTopUpCheckout","tags":["Card credits"],"summary":"Create a Stripe Checkout Session.","requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"A number from 0.5 through 2."},"accountId":{"type":"string","minLength":1,"maxLength":100},"challengeId":{"type":"string","minLength":1,"maxLength":100}}}}}},"responses":{"303":{"description":"Redirect to Stripe-hosted Checkout.","headers":{"Location":{"description":"Stripe Checkout URL.","schema":{"type":"string","format":"uri"}}}},"500":{"description":"Unexpected service or configuration failure."},"502":{"description":"Stripe did not create a usable Checkout Session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"The credit-account schema is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/top-up/complete":{"get":{"operationId":"completeTopUp","tags":["Card credits"],"summary":"Verify a returned Stripe Checkout Session and credit the account.","parameters":[{"name":"session_id","in":"query","required":true,"description":"Stripe Checkout Session id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout was credited or had already been credited.","content":{"text/html":{"schema":{"type":"string","description":"HTML rendered by the service."}}}},"400":{"description":"The session id is missing.","content":{"text/html":{"schema":{"type":"string","description":"HTML rendered by the service."}}}},"402":{"description":"The Checkout Session is not paid.","content":{"text/html":{"schema":{"type":"string","description":"HTML rendered by the service."}}}},"500":{"description":"Unexpected service or configuration failure."},"502":{"description":"Stripe returned an invalid session.","content":{"text/html":{"schema":{"type":"string","description":"HTML rendered by the service."}}}},"503":{"description":"The credit-account schema is not ready.","content":{"text/html":{"schema":{"type":"string","description":"HTML rendered by the service."}}}}}}},"/top-up/status":{"get":{"operationId":"getTopUpStatus","tags":["Card credits"],"summary":"Check whether a credit account is active after Checkout.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Credit account bearer id."},"required":false,"description":"Credit account bearer id.","name":"account","in":"query"}],"responses":{"200":{"description":"The credit account is active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpStatus"}}}},"400":{"description":"The account parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"404":{"description":"The credit account is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpStatus"}}}},"500":{"description":"Unexpected service or configuration failure."},"503":{"description":"The credit-account schema is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/credits/{accountId}":{"get":{"operationId":"getCreditAccount","tags":["Card credits"],"summary":"Get the balance of a prepaid credit account.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128,"example":"credit-account-bearer-token"},"required":true,"name":"accountId","in":"path"}],"responses":{"200":{"description":"Current account balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditAccount"}}}},"404":{"description":"The credit account does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Unexpected service or configuration failure."},"503":{"description":"The credit-account schema is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/tts/voices":{"get":{"operationId":"listTtsVoices","tags":["TTS"],"summary":"List supported public voice ids and current pricing.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Provider-qualified model id. Defaults to openai/tts-1."},"required":false,"description":"Provider-qualified model id. Defaults to openai/tts-1.","name":"model","in":"query"}],"responses":{"200":{"description":"Supported voices and pricing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoicesResponse"}}}},"400":{"description":"The requested model is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Unexpected service or configuration failure."}}}},"/tts/models":{"get":{"operationId":"listTtsModels","tags":["TTS"],"summary":"List selectable TTS models, limits, voices, and current pricing.","responses":{"200":{"description":"Selectable provider-qualified TTS models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsModelsResponse"}}}},"500":{"description":"Unexpected service or configuration failure."}}}},"/tts":{"post":{"operationId":"createCardCreditTts","tags":["TTS","Card credits"],"summary":"Synthesize speech using prepaid card credits.","parameters":[{"schema":{"type":"string","description":"Set to true to force asynchronous mode."},"required":false,"description":"Set to true to force asynchronous mode.","name":"async","in":"query"},{"schema":{"type":"string","description":"Set to false for asynchronous requests to opt out of audio retention."},"required":false,"description":"Set to false for asynchronous requests to opt out of audio retention.","name":"storeAudio","in":"query"},{"schema":{"type":"string","description":"Model id used only with a text/plain request body."},"required":false,"description":"Model id used only with a text/plain request body.","name":"model","in":"query"},{"schema":{"type":"string","description":"Voice id used only with a text/plain request body."},"required":false,"description":"Voice id used only with a text/plain request body.","name":"voice","in":"query"},{"schema":{"type":"string","description":"Playback speed used only with a text/plain request body."},"required":false,"description":"Playback speed used only with a text/plain request body.","name":"speed","in":"query"},{"schema":{"type":"string","maxLength":512},"required":false,"name":"idempotency-key","in":"header"},{"schema":{"type":"string","maxLength":128},"required":false,"name":"x-credit-account","in":"header"}],"requestBody":{"required":false,"description":"JSON is preferred. text/plain is supported for constrained clients.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsRequest"}},"text/plain":{"schema":{"type":"string","minLength":1,"maxLength":4096}}}},"responses":{"200":{"description":"Generated speech audio.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"x-credit-account":{"description":"Bearer id of the prepaid credit account.","schema":{"type":"string"}},"x-credit-balance":{"description":"Remaining account balance in micro-USD.","schema":{"type":"integer"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}},"audio/wav":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}}}},"202":{"description":"An asynchronous job was accepted.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"x-credit-account":{"description":"Bearer id of the prepaid credit account.","schema":{"type":"string"}},"x-credit-balance":{"description":"Remaining account balance in micro-USD.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsJob"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"402":{"description":"Payment or prepaid credit is required.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 challenge on direct machine-payment endpoints.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"413":{"description":"The request exceeds the selected model's input limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"429":{"description":"The request exceeded the rate limit.","headers":{"Retry-After":{"description":"Seconds before the client should retry.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests in the current policy window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Internal or deployment configuration failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"502":{"description":"An upstream payment or TTS service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}},"get":{"operationId":"createCardCreditTtsWithQuery","tags":["TTS","Card credits"],"summary":"Synthesize speech using a GET fallback and prepaid card credits.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":1500},"required":true,"name":"text","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"model","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"voice","in":"query"},{"schema":{"type":"string","description":"A number from 0.5 through 2."},"required":false,"description":"A number from 0.5 through 2.","name":"speed","in":"query"},{"schema":{"type":"string","description":"Set to true to force asynchronous mode."},"required":false,"description":"Set to true to force asynchronous mode.","name":"async","in":"query"},{"schema":{"type":"string","description":"Set to false to opt out of asynchronous audio retention."},"required":false,"description":"Set to false to opt out of asynchronous audio retention.","name":"storeAudio","in":"query"},{"schema":{"type":"string","maxLength":512},"required":false,"name":"idempotency-key","in":"header"},{"schema":{"type":"string","maxLength":128},"required":false,"name":"x-credit-account","in":"header"}],"responses":{"200":{"description":"Generated speech audio.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"x-credit-account":{"description":"Bearer id of the prepaid credit account.","schema":{"type":"string"}},"x-credit-balance":{"description":"Remaining account balance in micro-USD.","schema":{"type":"integer"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}},"audio/wav":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}}}},"202":{"description":"An asynchronous job was accepted.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"x-credit-account":{"description":"Bearer id of the prepaid credit account.","schema":{"type":"string"}},"x-credit-balance":{"description":"Remaining account balance in micro-USD.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsJob"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"402":{"description":"Payment or prepaid credit is required.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 challenge on direct machine-payment endpoints.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"413":{"description":"The request exceeds the selected model's input limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"429":{"description":"The request exceeded the rate limit.","headers":{"Retry-After":{"description":"Seconds before the client should retry.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests in the current policy window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Internal or deployment configuration failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"502":{"description":"An upstream payment or TTS service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/x402/tts/quote":{"post":{"operationId":"createX402TtsQuote","tags":["TTS","x402"],"summary":"Create a hash-bound x402 TTS quote without disclosing text.","description":"The quote binds text length, SHA-256, voice, speed, price, network, and payee. Use the returned token to obtain a PAYMENT-REQUIRED challenge from /x402/tts without sending raw text. The token expires at the returned expiresAt (X402_QUOTE_VALIDITY_SECONDS, 300s by default); after that /x402/tts returns 400 QUOTE_EXPIRED. Within its lifetime it is a reusable price quote rather than a one-time ticket — each spend is charged separately, because payment rather than the token is what is consumed. textSha256 cannot be checked here, since quoting exists precisely so the text is never sent; the binding is enforced at synthesis, where a mismatch returns 400 QUOTE_BODY_MISMATCH and nothing is charged. Quoting is optional: a client that already knows the price can post the ordinary body to /x402/tts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402QuoteRequest"}}}},"responses":{"200":{"description":"Signed, short-lived quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402QuoteResponse"}}}},"400":{"description":"The quote request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"Quote signing is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/x402/deposit":{"post":{"operationId":"createX402Deposit","tags":["x402 prepaid"],"summary":"Fund a prepaid x402 balance with one confirmed USDC payment.","description":"Pays once so later /x402/tts requests skip facilitator verification and on-chain settlement. The service reserves the payment identifier before settlement, then credits the spend-only balance only after the exact USDC transfer is confirmed on Base.","parameters":[{"schema":{"type":"string","description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry."},"required":false,"description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry.","name":"payment-signature","in":"header"},{"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Prepaid balance to spend. Mutually exclusive with payment-signature."},"required":false,"description":"Prepaid balance to spend. Mutually exclusive with payment-signature.","name":"x-x402-account","in":"header"},{"schema":{"type":"string","description":"Unique per request; consumed by the debit and never reusable."},"required":false,"description":"Unique per request; consumed by the debit and never reusable.","name":"x-x402-nonce","in":"header"},{"schema":{"type":"string","description":"Unix seconds after which the prepaid signature is rejected."},"required":false,"description":"Unix seconds after which the prepaid signature is rejected.","name":"x-x402-expiry","in":"header"},{"schema":{"type":"string","description":"Micro-USD spend cap authorized for this request."},"required":false,"description":"Micro-USD spend cap authorized for this request.","name":"x-x402-max-amount","in":"header"},{"schema":{"type":"string","description":"EIP-712 PrepaidRequest signature from x-x402-account."},"required":false,"description":"EIP-712 PrepaidRequest signature from x-x402-account.","name":"x-x402-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402DepositRequest"}}}},"responses":{"200":{"description":"The confirmed payment was credited to the payer.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402DepositResponse"}}}},"400":{"description":"The deposit amount or x402 payment payload is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"402":{"description":"An x402 payment is required.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 challenge for the deposit amount.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"409":{"description":"The payment identifier conflicts or the settlement transaction is not yet confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Unexpected service or configuration failure."},"502":{"description":"The payment service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"The prepaid schema or payment configuration is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/x402/accounts/{address}":{"get":{"operationId":"getX402PrepaidAccount","tags":["x402 prepaid"],"summary":"Get a prepaid x402 balance.","description":"Requires the same EIP-712 signature headers as a paid request. Deposits are visible on-chain, but consumption is not, so the balance is only disclosed to the address that owns it. A credential signed for a different address is rejected before the balance is read, so the 401 and 404 here distinguish 'you do not own this address' from 'you own it and have never deposited' — neither reveals anything about an address the caller cannot already sign for.","parameters":[{"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","example":"0x88E7960011C59BeE0088650CA52d7519B00381C8"},"required":true,"name":"address","in":"path"},{"schema":{"type":"string","description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry."},"required":false,"description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry.","name":"payment-signature","in":"header"},{"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Prepaid balance to spend. Mutually exclusive with payment-signature."},"required":false,"description":"Prepaid balance to spend. Mutually exclusive with payment-signature.","name":"x-x402-account","in":"header"},{"schema":{"type":"string","description":"Unique per request; consumed by the debit and never reusable."},"required":false,"description":"Unique per request; consumed by the debit and never reusable.","name":"x-x402-nonce","in":"header"},{"schema":{"type":"string","description":"Unix seconds after which the prepaid signature is rejected."},"required":false,"description":"Unix seconds after which the prepaid signature is rejected.","name":"x-x402-expiry","in":"header"},{"schema":{"type":"string","description":"Micro-USD spend cap authorized for this request."},"required":false,"description":"Micro-USD spend cap authorized for this request.","name":"x-x402-max-amount","in":"header"},{"schema":{"type":"string","description":"EIP-712 PrepaidRequest signature from x-x402-account."},"required":false,"description":"EIP-712 PrepaidRequest signature from x-x402-account.","name":"x-x402-signature","in":"header"}],"responses":{"200":{"description":"Current prepaid balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PrepaidAccount"}}}},"400":{"description":"The prepaid credential is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"401":{"description":"The signature does not belong to the requested address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"404":{"description":"The prepaid account does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Unexpected service or configuration failure."},"503":{"description":"The prepaid schema is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/x402/tts":{"post":{"operationId":"createX402Tts","tags":["TTS","x402"],"summary":"Synthesize speech using an exact per-request x402 USDC payment.","parameters":[{"schema":{"type":"string","description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry."},"required":false,"description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry.","name":"payment-signature","in":"header"},{"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Prepaid balance to spend. Mutually exclusive with payment-signature."},"required":false,"description":"Prepaid balance to spend. Mutually exclusive with payment-signature.","name":"x-x402-account","in":"header"},{"schema":{"type":"string","description":"Unique per request; consumed by the debit and never reusable."},"required":false,"description":"Unique per request; consumed by the debit and never reusable.","name":"x-x402-nonce","in":"header"},{"schema":{"type":"string","description":"Unix seconds after which the prepaid signature is rejected."},"required":false,"description":"Unix seconds after which the prepaid signature is rejected.","name":"x-x402-expiry","in":"header"},{"schema":{"type":"string","description":"Micro-USD spend cap authorized for this request."},"required":false,"description":"Micro-USD spend cap authorized for this request.","name":"x-x402-max-amount","in":"header"},{"schema":{"type":"string","description":"EIP-712 PrepaidRequest signature from x-x402-account."},"required":false,"description":"EIP-712 PrepaidRequest signature from x-x402-account.","name":"x-x402-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TtsPostBody"}}}},"responses":{"200":{"description":"Generated speech audio after settlement.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt.","schema":{"type":"string"}},"x-payment-identifier":{"description":"Stable identifier from the required official x402 Payment Identifier extension.","schema":{"type":"string"}},"x-idempotent-replay":{"description":"True when the response is the original cached audio and settlement receipt.","schema":{"type":"boolean"}},"x-x402-balance":{"description":"Remaining prepaid balance in micro-USD. Present only on prepaid requests, which carry no settlement receipt.","schema":{"type":"integer"}},"x-x402-charged":{"description":"Micro-USD retained for this request — the prepaid receipt. Present only on prepaid requests, which settled once at deposit time and so have no per-request PAYMENT-RESPONSE. 0 means the debit was restored.","schema":{"type":"integer"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"401":{"description":"The prepaid signature was not produced by the account being spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"402":{"description":"Payment or prepaid credit is required.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 challenge on direct machine-payment endpoints.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"405":{"description":"HEAD is not served. The response exists only once it has been paid for, so a HEAD would either synthesize unpaid or bill the caller for a body HEAD discards.","headers":{"allow":{"description":"Methods this endpoint serves.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"409":{"description":"The payment identifier conflicts with another request, its first request is still in progress, the prepaid nonce was already spent, or the payment outcome is unknown and must not be retried automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"413":{"description":"The request exceeds the selected model's input limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"429":{"description":"The request exceeded the rate limit.","headers":{"Retry-After":{"description":"Seconds before the client should retry.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests in the current policy window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Internal or deployment configuration failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"502":{"description":"An upstream payment or TTS service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}},"get":{"operationId":"createX402TtsWithQuery","tags":["TTS","x402"],"summary":"Synthesize speech using a GET fallback and x402 USDC payment.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":1500},"required":true,"name":"text","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"model","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"voice","in":"query"},{"schema":{"type":"string","description":"A number from 0.5 through 2."},"required":false,"description":"A number from 0.5 through 2.","name":"speed","in":"query"},{"schema":{"type":"string","description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry."},"required":false,"description":"Base64-encoded x402 v2 PaymentPayload used on the paid retry.","name":"payment-signature","in":"header"},{"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Prepaid balance to spend. Mutually exclusive with payment-signature."},"required":false,"description":"Prepaid balance to spend. Mutually exclusive with payment-signature.","name":"x-x402-account","in":"header"},{"schema":{"type":"string","description":"Unique per request; consumed by the debit and never reusable."},"required":false,"description":"Unique per request; consumed by the debit and never reusable.","name":"x-x402-nonce","in":"header"},{"schema":{"type":"string","description":"Unix seconds after which the prepaid signature is rejected."},"required":false,"description":"Unix seconds after which the prepaid signature is rejected.","name":"x-x402-expiry","in":"header"},{"schema":{"type":"string","description":"Micro-USD spend cap authorized for this request."},"required":false,"description":"Micro-USD spend cap authorized for this request.","name":"x-x402-max-amount","in":"header"},{"schema":{"type":"string","description":"EIP-712 PrepaidRequest signature from x-x402-account."},"required":false,"description":"EIP-712 PrepaidRequest signature from x-x402-account.","name":"x-x402-signature","in":"header"}],"responses":{"200":{"description":"Generated speech audio after settlement.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt.","schema":{"type":"string"}},"x-payment-identifier":{"description":"Stable identifier from the required official x402 Payment Identifier extension.","schema":{"type":"string"}},"x-idempotent-replay":{"description":"True when the response is the original cached audio and settlement receipt.","schema":{"type":"boolean"}},"x-x402-balance":{"description":"Remaining prepaid balance in micro-USD. Present only on prepaid requests, which carry no settlement receipt.","schema":{"type":"integer"}},"x-x402-charged":{"description":"Micro-USD retained for this request — the prepaid receipt. Present only on prepaid requests, which settled once at deposit time and so have no per-request PAYMENT-RESPONSE. 0 means the debit was restored.","schema":{"type":"integer"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary","description":"Generated speech audio bytes."}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"401":{"description":"The prepaid signature was not produced by the account being spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"402":{"description":"Payment or prepaid credit is required.","headers":{"x-trace-id":{"description":"Per-request trace identifier.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 challenge on direct machine-payment endpoints.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"405":{"description":"HEAD is not served. The response exists only once it has been paid for, so a HEAD would either synthesize unpaid or bill the caller for a body HEAD discards.","headers":{"allow":{"description":"Methods this endpoint serves.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"409":{"description":"The payment identifier conflicts with another request, its first request is still in progress, the prepaid nonce was already spent, or the payment outcome is unknown and must not be retried automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"413":{"description":"The request exceeds the selected model's input limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"415":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"429":{"description":"The request exceeded the rate limit.","headers":{"Retry-After":{"description":"Seconds before the client should retry.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests in the current policy window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"500":{"description":"Internal or deployment configuration failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"502":{"description":"An upstream payment or TTS service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"503":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}}}}