{"openapi":"3.0.3","info":{"title":"Sume Developer API","version":"1.0.0","description":"Public developer API contract for Sume. Authenticate with either `x-api-key: sume_live_...` or `Authorization: Bearer sume_live_...` — send exactly one; a request carrying both is rejected with `401 unauthorized`. Paid catalog entries expose Sume price estimates in credits; generation reserves credits from the workspace balance when the usage ledger is enabled."},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Sume developer API key created from the dashboard. Example: `x-api-key: sume_live_...`. Send exactly one credential: a request carrying both `x-api-key` and `Authorization: Bearer` is rejected with `401 unauthorized` (`Send only one API key credential.`)."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sume API key","description":"Sume developer API key sent as an HTTP bearer token. Example: `Authorization: Bearer sume_live_...`. Send exactly one credential: a request carrying both `x-api-key` and `Authorization: Bearer` is rejected with `401 unauthorized` (`Send only one API key credential.`)."}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","category","stage","retryable","retry_after_seconds","public_reason","next_action"],"properties":{"code":{"type":"string","pattern":"^[a-z0-9_]+$","description":"Stable machine token identifying the failure. Always matches `^[a-z0-9_]+$` — never a sentence, and never a value that varies with the request. Switch on this; `message` is for humans and may be reworded."},"message":{"type":"string"},"request_id":{"type":"string","pattern":"^req_[a-f0-9]{32}$","description":"Sume-owned HTTP request correlation id for debugging this API response. This is not a generation job id."},"category":{"type":"string","pattern":"^[a-z0-9_]+$"},"stage":{"type":"string","pattern":"^[a-z0-9_]+$"},"retryable":{"type":"boolean","description":"`true` when the same request can succeed later, unchanged; a retryable submit refusal frees its `Idempotency-Key`, so the same key runs again. The HTTP status gives the class; this flag also marks the one retryable refusal outside 429 and 5xx, `404 receipt_not_ready`."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Seconds to wait before retrying. Every retryable error that carries it also sends it as the `retry-after` header."},"public_reason":{"type":"string","pattern":"^[a-z0-9_]+$"},"next_action":{"type":"string","description":"What to do next: `fix_input` (change the request), `authenticate` (use a key that may call this), `add_funds`, `retry_later` (after `retry_after_seconds`), `poll_status` (the job is still running), `inspect_events` (the job ended; read its error or events) or `contact_support`.","enum":["fix_input","authenticate","add_funds","retry_later","poll_status","inspect_events","contact_support"]},"details":{},"metadata":{"type":"object","description":"Present when an upstream provider refused the request (today `provider_rate_limited`): `provider_name` (`HeyGen`, or `upstream` for providers Sume does not name), `error_type` (`rate_limit`), `provider_code` (the provider's own code), `is_byok` (always false) and `raw` (the provider's `status`, `code` and `message`).","properties":{"provider_name":{"type":"string"},"error_type":{"type":"string"},"provider_code":{"type":"string"},"is_byok":{"type":"boolean"},"raw":{"type":"object","properties":{"status":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"example":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"retry_after_seconds":null,"public_reason":"authentication_required","next_action":"authenticate"}}},"HealthResponse":{"type":"object","required":["service","status","build","runtime"],"properties":{"service":{"type":"string"},"status":{"type":"string"},"build":{"type":"object","required":["commit_sha","source_branch","build_id","build_time"],"properties":{"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA for the deployed API build, or null when unavailable."},"source_branch":{"type":"string","nullable":true,"description":"Source branch or ref for the deployed API build, or null when unavailable."},"build_id":{"type":"string","nullable":true,"description":"CI/build run identifier for correlating deployment logs, or null when unavailable."},"build_time":{"type":"string","format":"date-time","nullable":true,"description":"UTC timestamp when the deploy workflow generated build metadata, or null when unavailable."}}},"runtime":{"type":"object","required":["developerDbConfigured","apiKeyLedgerConfigured","databasePool"],"properties":{"developerDbConfigured":{"type":"boolean"},"apiKeyLedgerConfigured":{"type":"boolean"},"databasePool":{"type":"object","required":["max","idleTimeoutMs","connectionTimeoutMs"],"properties":{"max":{"type":"integer"},"idleTimeoutMs":{"type":"integer"},"connectionTimeoutMs":{"type":"integer"}}}}}},"example":{"service":"sume-com-api","status":"ok","build":{"commit_sha":"676bfcb5f1048edc7767bad63647bba6c8ec022b","source_branch":"main","build_id":"28311981273","build_time":"2026-06-28T05:07:26.000Z"},"runtime":{"developerDbConfigured":true,"apiKeyLedgerConfigured":true,"databasePool":{"max":5,"idleTimeoutMs":30000,"connectionTimeoutMs":5000}}}},"VersionHealthResponse":{"type":"object","required":["apiVersion","status","build"],"properties":{"apiVersion":{"type":"string"},"status":{"type":"string"},"build":{"type":"object","required":["commit_sha","source_branch","build_id","build_time"],"properties":{"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA for the deployed API build, or null when unavailable."},"source_branch":{"type":"string","nullable":true,"description":"Source branch or ref for the deployed API build, or null when unavailable."},"build_id":{"type":"string","nullable":true,"description":"CI/build run identifier for correlating deployment logs, or null when unavailable."},"build_time":{"type":"string","format":"date-time","nullable":true,"description":"UTC timestamp when the deploy workflow generated build metadata, or null when unavailable."}}}},"example":{"apiVersion":"v1","status":"ok","build":{"commit_sha":"676bfcb5f1048edc7767bad63647bba6c8ec022b","source_branch":"main","build_id":"28311981273","build_time":"2026-06-28T05:07:26.000Z"}}},"CatalogResponse":{"type":"object","required":["apiVersion","data","status"],"properties":{"apiVersion":{"type":"string"},"data":{"type":"array","items":{"type":"object","required":["id","name","api_type","model_id","model_ids","invoke_url","status","availability","runtime","billing","endpoints","resource_endpoints"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"api_type":{"type":"string","enum":["model_api","resource_api","job_api","asset_api"],"description":"Public API surface category. Model APIs submit by Sume-owned product model id; resource APIs manage durable Sume resources; Job APIs expose lifecycle; Asset APIs manage media inputs."},"model_id":{"type":"string","enum":["sume/avatar-1.0/generate","sume/avatar-1.0/talking-video","sume/avatar/v1.0","sume/avatar-video/v1.0","sume/avatar-face-swap/v1.0","sume/image-1.0","sume/image-router","sume/video-1.0","sume/video-router","sume/music-1.0","sume/music-router","sume/stt-1.0","sume/tts-1.0","sume/tts-router","sume/rmbg-1.0","sume/video-upscale-1.0","veed/fabric-1.0","sume/avatar-1.0/fabric","kling/3.0/motion-control","sume/timeline-1.0","sume/timeline-1.0/audio","sume/timeline-1.0/compose","sume/video-filter-1.0","sume/video-trim-1.0","sume/audio-detach-1.0","sume/voice-change-1.0","sume/dubbing-1.0","sume/video-inspect-1.0","sume/reference-ingest-1.0","sume/remix-media-1.0"],"nullable":true,"description":"Primary Sume-owned public model id for model-run invocation, or null for non-model utility capabilities."},"model_ids":{"type":"array","description":"Sume-owned public product model ids. Invoke them through the canonical `invoke_url` returned for each model; these ids intentionally hide raw provider endpoint ids.","items":{"type":"string","enum":["sume/avatar-1.0/generate","sume/avatar-1.0/talking-video","sume/avatar/v1.0","sume/avatar-video/v1.0","sume/avatar-face-swap/v1.0","sume/image-1.0","sume/image-router","sume/video-1.0","sume/video-router","sume/music-1.0","sume/music-router","sume/stt-1.0","sume/tts-1.0","sume/tts-router","sume/rmbg-1.0","sume/video-upscale-1.0","veed/fabric-1.0","sume/avatar-1.0/fabric","kling/3.0/motion-control","sume/timeline-1.0","sume/timeline-1.0/audio","sume/timeline-1.0/compose","sume/video-filter-1.0","sume/video-trim-1.0","sume/audio-detach-1.0","sume/voice-change-1.0","sume/dubbing-1.0","sume/video-inspect-1.0","sume/reference-ingest-1.0","sume/remix-media-1.0"]}},"invoke_url":{"type":"string","nullable":true,"description":"Primary public invocation URL for this capability, or null when the capability is read-only."},"status":{"type":"string","description":"Backward-compatible human-readable readiness status. Prefer `availability`, `runtime`, and `billing` for machine-readable decisions."},"availability":{"type":"string","enum":["available","degraded","unavailable","coming_soon"],"description":"Machine-readable capability availability for the current API runtime."},"beta":{"type":"boolean","description":"True for public beta capabilities whose contract is available before the full provider workflow is generally available."},"runtime":{"type":"object","required":["generation_configured","worker_configured","media_mirror_configured"],"properties":{"generation_configured":{"type":"boolean"},"worker_configured":{"type":"boolean"},"media_mirror_configured":{"type":"boolean"}}},"billing":{"type":"object","required":["requires_balance","top_up_available"],"properties":{"requires_balance":{"type":"boolean"},"top_up_available":{"type":"boolean"}}},"unavailable_reason":{"type":"string","nullable":true,"description":"Public-safe reason when a capability is unavailable in this runtime."},"degraded_reason":{"type":"string","nullable":true,"description":"Public-safe reason when a capability is available with known limitations."},"endpoints":{"type":"array","items":{"type":"string"}},"resource_endpoints":{"type":"array","description":"Concrete resource endpoints that remain stable aliases or richer resource APIs for this capability.","items":{"type":"string"}},"models":{"type":"array","items":{"type":"string"}},"pricing":{"type":"object","description":"Capability-level public pricing policy for paid model families. Every price is in credits.","required":["billing_unit","billable_amount","estimate_status","reservation_policy"],"properties":{"billing_unit":{"type":"string","enum":["credit"]},"billable_amount":{"type":"string","enum":["sume_price"],"description":"Sume developer API billing charges the public Sume price for this capability."},"estimate_status":{"type":"string","enum":["available"]},"reservation_policy":{"type":"string"}}},"model_pricing":{"type":"array","description":"Per-model public estimate in credits. For an authenticated workspace the credits are its own, under its own terms; anonymous callers read standard terms.","items":{"type":"object","required":["model","billing_unit","billable_amount","estimate_status","estimated_credits","minimum_credits","maximum_credits","pricing_basis"],"properties":{"model":{"type":"string"},"billing_unit":{"type":"string","enum":["credit"]},"billable_amount":{"type":"string","enum":["sume_price"]},"estimate_status":{"type":"string","enum":["available"]},"estimated_credits":{"type":"integer","minimum":0,"description":"Credits a request with only the required fields is charged."},"minimum_credits":{"type":"integer","minimum":0,"description":"Credits the smallest billable request is charged."},"maximum_credits":{"type":"integer","minimum":0,"description":"Credits the largest request this surface admits is charged."},"estimated_usd":{"type":"string","description":"estimated_credits in US dollars (rounded up to the cent). A band from the catalog's list cents, so it can sit a cent above the debit; dry_run gives the exact charge."},"minimum_usd":{"type":"string","description":"minimum_credits in US dollars."},"maximum_usd":{"type":"string","description":"maximum_credits in US dollars."},"pricing_basis":{"type":"string"},"title":{"type":"string"},"price":{"type":"string","description":"The unit price in credits, e.g. `63 credits`; read with `unit`."},"unit":{"type":"string"},"description":{"type":"string"}}}}}}},"status":{"type":"string"}},"example":{"apiVersion":"v1","status":"available","data":[{"id":"avatar-generation","name":"Avatar Generation","api_type":"model_api","model_id":"sume/avatar-1.0/generate","model_ids":["sume/avatar-1.0/generate","sume/avatar/v1.0","sume/avatar-1.0","sume/avatar/v1"],"invoke_url":"/v1/avatar-1.0/generate","status":"available","availability":"available","runtime":{"generation_configured":true,"worker_configured":true,"media_mirror_configured":true},"billing":{"requires_balance":true,"top_up_available":false},"endpoints":["POST /v1/avatar-1.0/generate","GET /v1/avatar-1.0/avatars","GET /v1/avatar-1.0/avatars/:id","POST /v1/models/sume/avatar-1.0/generate/runs","POST /v1/models/sume/avatar/v1.0/runs","POST /v1/avatars","GET /v1/avatars","GET /v1/jobs/:id/status","GET /v1/jobs/:id/result","GET /v1/avatars/:id"],"resource_endpoints":["GET /v1/avatar-1.0/avatars","GET /v1/avatar-1.0/avatars/:id","GET /v1/avatars","GET /v1/avatars/:id"],"models":["sume/avatar-1.0/generate","sume/avatar/v1.0"],"pricing":{"billing_unit":"credit","billable_amount":"sume_price","estimate_status":"available","reservation_policy":"Submit-time usage reservation holds the request's estimated credits, captures them on completion, and returns them when a job fails or is canceled before generation."},"model_pricing":[{"model":"sume/avatar-1.0/generate","billing_unit":"credit","billable_amount":"sume_price","estimate_status":"available","estimated_credits":60,"minimum_credits":60,"maximum_credits":60,"pricing_basis":"Create avatar: 60 credits per avatar. One-time avatar creation for reusable Sume Avatar 1.0 video workflows.","title":"Create avatar","price":"60 credits","unit":"per avatar","description":"One-time avatar creation for reusable Sume Avatar 1.0 video workflows."}]}]}},"AccountResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["account"],"properties":{"account":{"type":"object","required":["workspace_id","owner_user_id","api_key","auth_source"],"properties":{"workspace_id":{"type":"string"},"owner_user_id":{"type":"string"},"api_key":{"type":"object","required":["id","name","prefix","scopes"],"properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"auth_source":{"type":"string","enum":["ledger","env","dashboard","mcp_oauth"]}}}}}}},"WebhookSigningRotation":{"type":["null","object"],"description":"Set while a rotation's overlap window is open. During the window every delivery carries two comma-separated signatures in `x-sume-webhook-signature`, newest first, so a verifier holding either secret succeeds.","required":["previous_version","previous_fingerprint","previous_valid_until"],"properties":{"previous_version":{"type":["null","integer"],"description":"Derivation version of the rotated-away secret."},"previous_fingerprint":{"type":["null","string"],"description":"Fingerprint of the rotated-away secret, so a delivery signed before the rotation is still attributable."},"previous_valid_until":{"type":["null","string"],"format":"date-time","description":"When the rotated-away secret stops verifying. After this, only the current secret is signed with."}}},"WebhookSigningSecretResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["scope","version","fingerprint","secret"],"properties":{"scope":{"type":"string","description":"Recipient this secret belongs to: `workspace:{id}` for a team key, `user:{id}` for a personal one. Two members of the same team share a verifier, which is what a team integration expects."},"version":{"type":"integer","description":"Derivation version. Bumping it changes the secret; nothing bumps it today."},"fingerprint":{"type":"string","description":"Non-reversible fingerprint of `secret`, matching `x-sume-webhook-secret-fingerprint` on deliveries and `webhook_delivery.signing_secret_fingerprint` on receipts. Safe to quote in a support ticket; the secret is not."},"secret":{"type":"string","description":"The signing secret for this recipient, 64 hex characters. Pass it to `verifyWebhook` from `@sume-com/client`, or use it as the HMAC-SHA256 key over `{timestamp}.{raw body}`. It covers both job (`job.*`) and run (`format.run.terminal`) webhooks."},"rotation":{"$ref":"#/components/schemas/WebhookSigningRotation"}}}}},"WebhookSigningSecretRotateResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["scope","version","fingerprint","secret","rotation"],"properties":{"scope":{"type":"string","description":"Recipient the new secret belongs to."},"version":{"type":"integer","description":"Derivation version after the rotation. Increments by one each time."},"fingerprint":{"type":"string","description":"Fingerprint of the new secret. Deliveries carry it as `x-sume-webhook-secret-fingerprint` from now on, including during the overlap window — it names the secret to move to, not the one still being accepted."},"secret":{"type":"string","description":"The new signing secret, 64 hex characters. Install it on your receiver before `rotation.previous_valid_until`."},"rotation":{"$ref":"#/components/schemas/WebhookSigningRotation"}}}}},"WebhookTestDeliveryRequest":{"type":"object","required":["webhook_url"],"additionalProperties":false,"properties":{"webhook_url":{"type":"string","format":"uri","description":"Public HTTPS URL to POST a dummy `webhook.test` event to. Localhost, private-network, and non-HTTPS URLs are rejected. This is not a redeliver of a real job or Format run."}}},"WebhookTestDeliveryResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["object","event_type","url","status_code","delivered_at","error","signature_version","signing_secret_fingerprint"],"properties":{"object":{"type":"string","enum":["webhook.test_delivery"]},"event_type":{"type":"string","enum":["webhook.test"]},"url":{"type":"string","format":"uri"},"status_code":{"type":"integer","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true},"signature_version":{"type":"string"},"signing_secret_fingerprint":{"type":"string"}}}}},"WebhookRedeliverResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","webhook_delivery","redelivery"],"properties":{"id":{"type":"string"},"webhook_delivery":{"$ref":"#/components/schemas/WebhookDelivery"},"redelivery":{"type":"object","description":"What the manual POST itself got back. Read this, not `webhook_delivery.last_status_code`: a failed redeliver of an already delivered call leaves the row on the automatic 2xx that arrived.","required":["delivered","status_code","error"],"properties":{"delivered":{"type":"boolean"},"status_code":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true}}}}}}},"FormatRunWebhookRedeliverResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","webhook_delivery","redelivery"],"properties":{"id":{"type":"string"},"webhook_delivery":{"$ref":"#/components/schemas/RunWebhookDelivery"},"redelivery":{"type":"object","description":"What the manual POST itself got back. Read this, not `webhook_delivery.last_status_code`: a failed redeliver of an already delivered call leaves the row on the automatic 2xx that arrived.","required":["delivered","status_code","error"],"properties":{"delivered":{"type":"boolean"},"status_code":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true}}}}}}},"PublicDeveloperApiCreditBalance":{"type":"object","description":"Workspace-scoped credits balance visible to the authenticated API key. Missing balance rows are represented as an explicit zero balance instead of an internal error.","required":["available_credits","state","updated_at","expiration"],"properties":{"available_credits":{"type":"integer","minimum":0,"description":"Credits the workspace can spend now, rounded down: never more than the wallet will spend."},"available_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same balance in US dollars, rounded down to the cent: the figure to quote to a person."},"state":{"type":"string","enum":["funded","empty"],"description":"`empty` means the workspace has no spendable credits or no balance row yet."},"updated_at":{"type":"string","format":"date-time","nullable":true},"invoice":{"type":"object","description":"Present when the workspace is invoiced (pays afterward): its runs are held to this billing period's invoice limit, not to `available_usd`.","required":["limit_usd","used_usd","remaining_usd","period_end"],"properties":{"limit_usd":{"type":"string","nullable":true,"description":"This period's invoice limit; null means no limit."},"used_usd":{"type":"string","description":"What this period has already put on the invoice."},"remaining_usd":{"type":"string","nullable":true,"description":"Room left under the limit; null means no limit."},"period_end":{"type":"string","format":"date-time"}}},"expiration":{"type":"object","description":"Expiry summary for currently spendable credit lots. Amounts exclude expired, reserved, captured, or depleted credits.","required":["next_expires_at","next_expiring_credits","expiring_soon_days","expiring_soon_credits"],"properties":{"next_expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Earliest expiration timestamp among currently spendable credit lots, or null when no credits are spendable."},"next_expiring_credits":{"type":"integer","minimum":0,"description":"Spendable credits expiring at `next_expires_at`."},"expiring_soon_days":{"type":"integer","description":"Window used for the expiring-soon credits."},"expiring_soon_credits":{"type":"integer","minimum":0,"description":"Spendable credits expiring within the expiring-soon window."}}}}},"BalanceResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["balance"],"properties":{"balance":{"$ref":"#/components/schemas/PublicDeveloperApiCreditBalance"}}}}},"TrendingVideosSearchRequest":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","enum":["tiktok"],"default":"tiktok","description":"Trend discovery platform. The MVP supports only `tiktok`; unsupported platforms are rejected."},"query":{"type":"string","maxLength":200,"description":"Brand, product, creator, or keyword. Omit or leave empty to browse the current licensed TikTok trending feed. Known SaaS profiles apply stricter relevance and view filters on search."},"window":{"type":"string","enum":["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"],"description":"TikTok search time window. Browse and generic queries default to `this-week`; known SaaS profiles default to `last-3-months`. Videos older than the window are dropped."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum ranked videos to return. Search default is 20; browse (no query) default is 48. Quality filters may return fewer than this value instead of padding weak matches."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Optional two-letter TikTok region/country code for the search. Browse without a region fans out across US, GB, and KR trending feeds."},"summary_mode":{"type":"string","enum":["none","metadata","transcript"],"default":"none","description":"`none` returns metadata only. `metadata` returns a lightweight metadata-derived summary. `transcript` currently returns metadata plus an unsupported warning."},"download":{"type":"boolean","default":false,"description":"Reserved for a future mirroring workflow. The MVP does not download or mirror videos."},"download_limit":{"type":"integer","minimum":0,"maximum":100,"default":0,"description":"Reserved for a future mirroring workflow. Values above zero return an unsupported warning."}},"description":"Rebuild of POST /v1/trending-videos/search. On for the development API (api.dev). Production stays off until the rebuild is explicitly enabled."},"TrendingVideosSearchResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["platform","query","fetched_at","params","count","videos","warnings","usage"],"properties":{"platform":{"type":"string","enum":["tiktok"]},"query":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"params":{"type":"object","required":["platform","query","profile","region","window","limit","search_queries","sort_modes","summary_mode","download","download_limit","min_relevance","min_views"],"properties":{"platform":{"type":"string","enum":["tiktok"]},"query":{"type":"string"},"mode":{"type":"string","enum":["browse","search"],"description":"`browse` is the no-query trending feed. `search` is a filtered keyword/top query."},"profile":{"type":"string","nullable":true,"description":"Known Sume query profile used for relevance terms and strict filters, or null for generic searches and browse."},"region":{"type":"string","nullable":true},"window":{"type":"string","enum":["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"]},"limit":{"type":"integer"},"search_queries":{"type":"array","items":{"type":"string"}},"sort_modes":{"type":"array","items":{"type":"string","enum":["most-liked","relevance","date-posted"]}},"summary_mode":{"type":"string","enum":["none","metadata","transcript"]},"download":{"type":"boolean"},"download_limit":{"type":"integer"},"min_relevance":{"type":"number","nullable":true,"description":"Minimum relevance score enforced for search, or null for browse."},"min_views":{"type":"integer","nullable":true,"description":"Minimum view count enforced for search, or null for browse."},"cached":{"type":"boolean","description":"True when this response was served from the in-process trending cache."}}},"count":{"type":"integer"},"videos":{"type":"array","items":{"type":"object","required":["platform","rank","id","url","description","content_type","created_at","region","author","metrics","relevance","scores","source","summary"],"properties":{"platform":{"type":"string","enum":["tiktok"]},"rank":{"type":"integer"},"id":{"type":"string","description":"TikTok video id used for dedupe. This is not a raw provider payload id."},"url":{"type":"string","format":"uri","description":"Canonical public TikTok watch URL. Raw TikTok CDN media URLs are not returned."},"cover_url":{"type":"string","format":"uri","nullable":true,"description":"Optional display thumbnail from the provider cover image. Not a downloadable video URL."},"description":{"type":"string"},"content_type":{"type":"string"},"created_at":{"type":"string","format":"date-time","nullable":true},"region":{"type":"string","nullable":true},"author":{"type":"object","required":["handle","nickname","verified"],"properties":{"handle":{"type":"string","nullable":true},"nickname":{"type":"string","nullable":true},"verified":{"type":"boolean"}}},"metrics":{"type":"object","required":["views","likes","comments","shares","saves","engagement_rate","bayesian_like_rate","bayesian_comment_rate","bayesian_share_save_rate"],"properties":{"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"engagement_rate":{"type":"number"},"bayesian_like_rate":{"type":"number"},"bayesian_comment_rate":{"type":"number"},"bayesian_share_save_rate":{"type":"number"}}},"relevance":{"type":"object","required":["score","reason"],"properties":{"score":{"type":"number","minimum":0,"maximum":1},"reason":{"type":"string"}}},"scores":{"type":"object","required":["viral_score","relevance_score","base_score","components"],"properties":{"viral_score":{"type":"number"},"relevance_score":{"type":"number"},"base_score":{"type":"number"},"components":{"type":"object","required":["views_score","velocity_score","like_score","comment_score","share_save_score","recency_score","multi_surface_score","view_confidence","recency_damping","creator_diversity_penalty"],"properties":{"views_score":{"type":"number"},"velocity_score":{"type":"number"},"like_score":{"type":"number"},"comment_score":{"type":"number"},"share_save_score":{"type":"number"},"recency_score":{"type":"number"},"multi_surface_score":{"type":"number"},"view_confidence":{"type":"number"},"recency_damping":{"type":"number"},"creator_diversity_penalty":{"type":"number"}}}}},"source":{"type":"object","required":["surfaces","sort_modes","search_queries"],"properties":{"surfaces":{"type":"array","items":{"type":"string","enum":["keyword","top","trending-feed"]}},"sort_modes":{"type":"array","items":{"type":"string","enum":["most-liked","relevance","date-posted"]}},"search_queries":{"type":"array","items":{"type":"string"}}}},"summary":{"type":"string","nullable":true}}}},"warnings":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["partial_provider_results","profile_filters_limited_results","download_not_supported","transcript_summary_not_supported"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"usage":{"type":"object","required":["status","reserved_credits","captured_credits","refunded_credits","released_credits","final","updated_at"],"properties":{"status":{"type":"string","enum":["reserved","captured","refunded"]},"reserved_credits":{"type":"integer","minimum":0},"captured_credits":{"type":"integer","minimum":0},"refunded_credits":{"type":"integer","minimum":0},"released_credits":{"type":"integer","minimum":0},"reserved_usd_cents":{"type":"integer","minimum":0},"captured_usd_cents":{"type":"integer","minimum":0},"refunded_usd_cents":{"type":"integer","minimum":0},"released_usd_cents":{"type":"integer","minimum":0},"final":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}},"description":"Sume usage ledger summary for the per-search charge (7 credits), in credits. Successful searches return captured credits; provider failures return the reservation before returning an error."}}}}},"TrendingResearchSearchRequest":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":200,"description":"Typed niche. Wins over Brand DNA / business category when both are sent."},"category":{"type":"string","minLength":1,"maxLength":200,"description":"Workspace Brand DNA / business category used when `query` is omitted."},"brand_position":{"type":"string","minLength":1,"maxLength":200,"description":"Fallback Brand DNA position used when `query` and `category` are omitted."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":12}},"description":"TikTok + Instagram (Meta) trending research. YouTube is unsupported. Each accepted search uses 7 credits."},"TrendingResearchSearchResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["query","niche_source","fetched_at","platforms","count","videos","warnings"],"properties":{"query":{"type":"string"},"niche_source":{"type":"string","enum":["typed","brand_category","brand_position"]},"fetched_at":{"type":"string"},"platforms":{"type":"array","items":{"type":"string","enum":["tiktok","instagram"]}},"count":{"type":"integer"},"videos":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["platform","rank","id","url","cover_url","description","created_at","author","metrics"],"properties":{"platform":{"type":"string","enum":["tiktok","instagram"]},"rank":{"type":"integer"},"id":{"type":"string"},"url":{"type":"string"},"cover_url":{"type":"string","nullable":true},"description":{"type":"string"},"created_at":{"type":"string","nullable":true},"author":{"type":"object","additionalProperties":false,"required":["handle","nickname"],"properties":{"handle":{"type":"string","nullable":true},"nickname":{"type":"string","nullable":true}}},"metrics":{"type":"object","additionalProperties":false,"required":["views","likes","comments","shares"],"properties":{"views":{"type":"number","nullable":true},"likes":{"type":"number","nullable":true},"comments":{"type":"number","nullable":true},"shares":{"type":"number","nullable":true}}}}}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}},"usage":{"type":"object","additionalProperties":true}}}}},"InfluencerSearchRequest":{"type":"object","additionalProperties":false,"properties":{"niche":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or category niche. Required when `query` is omitted."},"query":{"type":"string","minLength":1,"maxLength":400,"description":"Natural-language brief. Required when `niche` is omitted."},"platforms":{"type":"array","items":{"type":"string","enum":["ig","tt","yt"]},"description":"Defaults to Instagram + TikTok (`ig`, `tt`)."},"geo":{"type":"string","minLength":1,"maxLength":80,"description":"Audience geo hint (country or city). Forwarded as relevance text."},"language":{"type":"string","minLength":1,"maxLength":32},"follower_min":{"type":"integer","minimum":0},"follower_max":{"type":"integer","minimum":0},"engagement_min":{"type":"number","minimum":0,"maximum":1},"limit":{"type":"integer","minimum":1,"maximum":24,"default":12}},"description":"Cold creator discovery via fixtures (no Modash key) or Modash Discovery. Provide `niche` or `query`. Unbilled — no Sume SKU. Not the platform avatar catalog."},"InfluencerSearchResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["source","query","fetched_at","count","creators","markdown","warnings"],"properties":{"source":{"type":"string","enum":["fixture","modash"]},"query":{"type":"object","additionalProperties":false,"required":["niche","platforms","geo","language","followerMin","followerMax","engagementMin","query","limit"],"properties":{"niche":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string","enum":["ig","tt","yt"]}},"geo":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"followerMin":{"type":"integer","nullable":true},"followerMax":{"type":"integer","nullable":true},"engagementMin":{"type":"number","nullable":true},"query":{"type":"string","nullable":true},"limit":{"type":"integer"}}},"fetched_at":{"type":"string"},"count":{"type":"integer"},"creators":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","platform","handle","displayName","profileUrl","followers","engagementRate","bio","lookalikeTags","audience","whyFit","avatarUrl"],"properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"handle":{"type":"string"},"displayName":{"type":"string"},"profileUrl":{"type":"string"},"followers":{"type":"integer"},"engagementRate":{"type":"number"},"bio":{"type":"string"},"lookalikeTags":{"type":"array","items":{"type":"string"}},"audience":{"type":"object","additionalProperties":false,"required":["geo","language","gender","ageBuckets"],"properties":{"geo":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"ageBuckets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["label","weight"],"properties":{"label":{"type":"string"},"weight":{"type":"number"}}}}}},"whyFit":{"type":"string"},"avatarUrl":{"type":"string","nullable":true}}}},"markdown":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"PublicDeveloperApiUsageRecord":{"type":"object","description":"Public usage ledger row scoped to the authenticated workspace, in credits. Raw provider task ids, provider URLs, idempotency keys, and internal user ids are omitted.","required":["id","request_id","job_id","operation_type","status","credits","auth_source","created_at","updated_at","captured_at","refunded_at"],"properties":{"byok":{"type":"object","nullable":true,"additionalProperties":false,"description":"The workspace's own provider key paid the model; the row's credits are the Sume share only.","required":["provider"],"properties":{"provider":{"type":"string","enum":["fal","vercel-ai-gateway"]}}},"id":{"type":"string"},"request_id":{"type":"string","nullable":true,"description":"Sume generation job/request id when the usage row is tied to a job."},"job_id":{"type":"string","nullable":true},"operation_type":{"type":"string"},"status":{"type":"string","enum":["reserved","captured","refunded"]},"credits":{"type":"integer","minimum":0,"description":"The row's credits: the hold while reserved, what the wallet kept once captured, what came back once refunded. Rounded up, so a paid row never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The row's amount in US dollars, rounded up to the cent like its credits: the figure to quote to a person."},"auth_source":{"type":"string","enum":["api_key"],"nullable":true,"description":"Non-identifying authentication source. API key ids and prefixes are intentionally omitted."},"thread_id":{"type":"string","nullable":true,"description":"Studio Agent thread the row was reserved from, or null for rows outside a thread."},"run_id":{"type":"string","nullable":true,"description":"Format / Action / Agent run (arun_…) the row belongs to, or null."},"turn_job_id":{"type":"string","nullable":true,"description":"The agent turn (studio-agent job id) that commissioned this row, or null for rows outside a turn. Pass it as job_id to sum the turn and everything it started."},"script_run_id":{"type":"string","nullable":true,"description":"The MCP script_run call (scr_…) that dispatched this row's job, or null when the job was called directly."},"script_run_call_index":{"type":"integer","minimum":1,"nullable":true,"description":"1-based index of the sume.call inside that script."},"settle_state":{"type":"string","nullable":true,"description":"Orthogonal to status: a reserved row in pending_usage / pending_topup / unpriced / model_mismatch is a hold the settle sweeper still owns."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"captured_at":{"type":"string","format":"date-time","nullable":true},"refunded_at":{"type":"string","format":"date-time","nullable":true}}},"UsageListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["usage","limit"],"properties":{"usage":{"type":"array","items":{"$ref":"#/components/schemas/PublicDeveloperApiUsageRecord"}},"limit":{"type":"integer","description":"Maximum number of newest usage rows requested by the client."},"summary":{"type":"object","nullable":true,"description":"Present when thread_id, run_id or job_id was given: the credits of that scope, summed over every ledger row it caused (not only the rows listed). debited_credits is what the wallet deducted (captured rows); held and refunded credits are not spend. Quote debited_credits, never a sum of rows. Null on the plain newest-rows list.","required":["scope","debited_credits","held_credits","refunded_credits","pending_credits","final","truncated","first_row_at","last_row_at","rows","includes","by_operation_type","script_runs","runs","cap"],"properties":{"scope":{"type":"object","required":["workspace_id","thread_id","run_id","job_id"],"properties":{"workspace_id":{"type":"string","nullable":true},"thread_id":{"type":"string","nullable":true},"run_id":{"type":"string","nullable":true},"job_id":{"type":"string","nullable":true}}},"debited_credits":{"type":"integer","minimum":0,"description":"What the wallet deducted (captured rows), rounded up once from the exact sum."},"held_credits":{"type":"integer","minimum":0,"description":"Holds of reserved rows, parked pending_* rows included. Not spend yet."},"refunded_credits":{"type":"integer","minimum":0,"description":"Holds of refunded rows. Given back; not spend."},"pending_credits":{"type":"integer","minimum":0,"description":"Holds of reserved rows parked pending_*, awaiting the settle sweeper."},"debited_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"debited_credits in US dollars: the same exact sum rounded up once to the cent. The figure to quote to a person."},"held_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"held_credits in US dollars."},"refunded_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"refunded_credits in US dollars."},"pending_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"pending_credits in US dollars."},"final":{"type":"boolean","description":"True once no hold is open: debited_credits will not move."},"hold_counts":{"type":"object","description":"What each still-reserved row is waiting on; the three sum to rows.reserved. open: a running turn or generation. browser_session: a Browser session's ceiling, settled when the session ends. billing_pending: work that ended and is being priced.","required":["open","browser_session","billing_pending"],"properties":{"open":{"type":"integer","minimum":0},"browser_session":{"type":"integer","minimum":0},"billing_pending":{"type":"integer","minimum":0}}},"holds":{"type":"array","description":"The reserved rows themselves, newest first, at most 50. hold_counts counts every reserved row.","items":{"type":"object","required":["usage_id","operation_type","kind","state","credits","opened_at","settle_state"],"properties":{"usage_id":{"type":"string"},"operation_type":{"type":"string"},"kind":{"type":"string","enum":["turn","generation","browser_session","sidecar","other"]},"state":{"type":"string","enum":["open","billing_pending"]},"credits":{"type":"integer","minimum":0},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"opened_at":{"type":"string","format":"date-time"},"settle_state":{"type":"string","nullable":true}}}},"truncated":{"type":"boolean","description":"True when the scope has more rows than the fold takes (5000); the figures then cover the newest rows only."},"first_row_at":{"type":"string","format":"date-time","nullable":true},"last_row_at":{"type":"string","format":"date-time","nullable":true},"rows":{"type":"object","required":["total","captured","reserved","refunded","pending"],"properties":{"total":{"type":"integer","minimum":0},"captured":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"refunded":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}}},"includes":{"type":"object","description":"What kinds of rows the sum covers. script_run_children counts rows a script_run call dispatched (they are generation jobs too); children created before the stamp existed count only as generation jobs.","required":["llm_turns","sidecars","browser_sessions","generation_jobs","other","refunded_rows","byok_rows","script_run_children"],"properties":{"llm_turns":{"type":"integer","minimum":0},"sidecars":{"type":"integer","minimum":0},"browser_sessions":{"type":"integer","minimum":0},"generation_jobs":{"type":"integer","minimum":0},"other":{"type":"integer","minimum":0},"refunded_rows":{"type":"integer","minimum":0},"byok_rows":{"type":"integer","minimum":0},"script_run_children":{"type":"integer","minimum":0,"nullable":true,"description":"Rows dispatched by a script_run call (the script_run_id stamp)."}}},"script_runs":{"type":"array","description":"The script_run calls inside the scope, by their stamp, most credits first; empty when none.","items":{"type":"object","required":["script_run_id","rows","debited_credits","held_credits","refunded_credits"],"properties":{"script_run_id":{"type":"string"},"rows":{"type":"integer","minimum":0},"debited_credits":{"type":"integer","minimum":0},"held_credits":{"type":"integer","minimum":0},"refunded_credits":{"type":"integer","minimum":0},"debited_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"held_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"refunded_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}}},"by_operation_type":{"type":"array","items":{"type":"object","required":["operation_type","rows","debited_credits","held_credits","refunded_credits"],"properties":{"operation_type":{"type":"string"},"rows":{"type":"integer","minimum":0},"debited_credits":{"type":"integer","minimum":0},"held_credits":{"type":"integer","minimum":0},"refunded_credits":{"type":"integer","minimum":0},"debited_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"held_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"refunded_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}}},"runs":{"type":"array","nullable":true,"description":"Thread scope only: the runs the thread hosted.","items":{"type":"object","required":["run_id","rows","debited_credits","held_credits","refunded_credits"],"properties":{"run_id":{"type":"string"},"rows":{"type":"integer","minimum":0},"debited_credits":{"type":"integer","minimum":0},"held_credits":{"type":"integer","minimum":0},"refunded_credits":{"type":"integer","minimum":0},"debited_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"held_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"refunded_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}}},"cap":{"type":"object","nullable":true,"description":"Run scope only: the generation cap's own accounting — reserved + captured generation rows attributed to the run, the agent's LLM class excluded. This is the cap gate's figure, never the run's total.","required":["limit_credits","counted_credits","remaining_credits"],"properties":{"limit_credits":{"type":"integer","minimum":0,"nullable":true,"description":"The ceiling, or null when the run has none or none was recorded."},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":"integer","minimum":0,"nullable":true},"limit_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","nullable":true},"counted_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"remaining_usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","nullable":true}}}}}}}}},"PublicArtifact":{"type":"object","description":"A Sume-hosted generated media artifact. Public artifact URLs use opaque Sume media CDN paths and omit raw source URLs, workspace ids, user ids, job ids, and workflow details. Clients must not parse artifact URLs.","required":["id","type","url","content_type"],"properties":{"id":{"type":"string","description":"Opaque public artifact identifier. This value is safe to log and display, but clients should treat it as an opaque token."},"public_artifact_id":{"type":"string","nullable":true,"description":"Opaque public artifact identifier for this generated media object."},"visibility":{"type":"string","nullable":true,"enum":["public_by_link"],"description":"Current public access policy for the generated media object."},"stage":{"type":"string","nullable":true,"description":"Provider-neutral Sume artifact stage when available, such as `first_frame`, `pose_frame`, or `scene_preview`."},"type":{"type":"string","enum":["image","video","audio","model","file"],"description":"`file` is a generic generated artifact category for outputs only. Avatar photo inputs use `input.image_url`, not a `file` request object."},"url":{"type":"string","format":"uri","description":"Public Sume CDN URL for the mirrored artifact. The path is opaque and must not be parsed for user, workspace, job, or provider identifiers."},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"checksum_sha256":{"type":"string","nullable":true}}},"PublicResourceSummary":{"type":"object","description":"Public resource summary backed by the Sume job lifecycle. Raw provider URLs, task ids, and provider secrets are omitted.","required":["id","object","status","resource_status","job_status","job_id","status_url","result_url","created_at","updated_at","completed_at","artifacts"],"properties":{"id":{"type":"string","description":"Resource id when available from a completed result; otherwise the linked Sume job id while dedicated resource storage is pending."},"object":{"type":"string","enum":["avatar","avatar_video"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"description":"Backward-compatible job lifecycle status. Prefer `resource_status` for resource readiness and `job_status` for job polling state."},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"],"description":"Resource-facing state. `ready` means the resource output is usable; queued/processing jobs map to `processing`, completed jobs map to `ready`, and canceled jobs map to `canceled`."},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"description":"Underlying Sume job lifecycle status for polling and result semantics."},"job_id":{"type":"string"},"handle":{"type":"string","description":"Avatar handle when this summary represents an avatar with a durable handle."},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Representative public Sume-hosted preview image URL when available. Avatar summaries use the avatar image; avatar_video summaries use normalized scene photos or mirrored generated scene/first-frame images."},"preview_video_url":{"type":"string","format":"uri","nullable":true,"description":"Representative public Sume-hosted avatar preview video URL when available."},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"scene":{"type":"object","nullable":true,"required":["type","status","preview_image_url"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"]},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"]},"preview_image_url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri"}},"additionalProperties":false},"scene_previews":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicAvatarVideoScenePreview"},"description":"Avatar Video scene preview metadata when this summary represents an avatar_video. Null for avatar summaries."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicArtifact"}},"voice":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"type":"string","enum":["processing","ready","failed"],"description":"Voice preparation state for an avatar summary; null for avatar_video and for an avatar with no voice. An avatar whose voice is `ready` is the selector POST /v1/tts-1.0/generate resolves from `avatar_id` / `avatar_handle` — the public route to a TTS voice."}}},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarProfileMetadata"},{"$ref":"#/components/schemas/PublicAvatarVideoMetadataSummary"},{"type":"null"}],"description":"Public-safe metadata when this summary represents an avatar or avatar_video and metadata is available. Internal drafts, provider payloads, signed/private URLs, and raw prompts are omitted."}}},"PublicAvatarProfileMetadata":{"type":"object","description":"Text-complete, public-safe avatar profile metadata for agent selection. Core profile fields are scene-agnostic; settings, camera, props, pose, and product-placement observations belong only under sample_media.","required":["version","persona","appearance","suitability","sample_media","search","provenance"],"properties":{"version":{"type":"string","enum":["avatar_profile_v1"]},"persona":{"type":"object","required":["short_summary","long_profile","creator_archetypes","role_archetypes","default_demeanor","speaking_style","language_fit"],"properties":{"short_summary":{"type":"string"},"long_profile":{"type":"string"},"creator_archetypes":{"type":"array","items":{"type":"string"}},"role_archetypes":{"type":"array","items":{"type":"string"}},"default_demeanor":{"type":"array","items":{"type":"string"}},"speaking_style":{"type":"object","required":["tone","energy","pace"],"properties":{"tone":{"type":"array","items":{"type":"string"}},"energy":{"type":"string","enum":["low","medium","high"]},"pace":{"type":"string","enum":["slow","medium","fast"]},"delivery_notes":{"type":"string"}}},"language_fit":{"type":"array","items":{"type":"object","required":["language","confidence","source"],"properties":{"language":{"type":"string"},"market_fit":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"]},"source":{"type":"string"}}}}}},"appearance":{"type":"object","required":["text_complete_description","realism_level","source","confidence","visibility"],"properties":{"text_complete_description":{"type":"string"},"apparent_age_band":{"type":"string","enum":["teens","20s","30s","40s","50s_plus","ambiguous"]},"gender_presentation":{"type":"string","enum":["feminine","masculine","androgynous","ambiguous"]},"hair_description":{"type":"string"},"styling_description":{"type":"string"},"wardrobe_baseline":{"type":"string"},"realism_level":{"type":"string","enum":["photoreal","stylized","illustrative"]},"source":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"]},"visibility":{"type":"string","enum":["public","owner","admin"]}}},"suitability":{"type":"object","required":["best_for","acceptable_for","avoid_for","product_categories","audience_fit","campaign_styles","casting_notes"],"properties":{"best_for":{"type":"array","items":{"type":"string"}},"acceptable_for":{"type":"array","items":{"type":"string"}},"avoid_for":{"type":"array","items":{"type":"string"}},"product_categories":{"type":"array","items":{"type":"string"}},"audience_fit":{"type":"array","items":{"type":"string"}},"campaign_styles":{"type":"array","items":{"type":"string"}},"brand_safety_notes":{"type":"string"},"casting_notes":{"type":"string"},"use_case_scores":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":1}}}},"sample_media":{"type":"array","items":{"type":"object","required":["asset_role","media_type","source","confidence"],"properties":{"asset_role":{"type":"string"},"media_type":{"type":"string","enum":["image","video","audio"]},"public_url":{"type":"string","format":"uri"},"artifact_id":{"type":"string"},"observed_setting":{"type":"string"},"observed_framing":{"type":"string"},"observed_lighting":{"type":"string"},"observed_pose":{"type":"string"},"observed_expression":{"type":"string"},"observed_wardrobe":{"type":"string"},"product_present":{"type":"boolean"},"voice_notes":{"type":"string"},"source":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"]}}}},"search":{"type":"object","required":["search_card","keywords","negative_keywords","embedding_text"],"properties":{"search_card":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"negative_keywords":{"type":"array","items":{"type":"string"}},"embedding_text":{"type":"string","description":"Public-safe text intended for future embedding/search pipelines. It does not include raw provider output or private media URLs."},"last_embedded_at":{"type":"string","format":"date-time"},"embedding_version":{"type":"string"}}},"provenance":{"type":"object","required":["created_by","updated_at","section_sources","section_confidence"],"properties":{"created_by":{"type":"string"},"reviewed_by":{"type":"string"},"reviewed_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"section_sources":{"type":"object","additionalProperties":{"type":"string"}},"section_confidence":{"type":"object","additionalProperties":{"type":"string","enum":["low","medium","high"]}}}}}},"PublicLinkedResource":{"type":"object","nullable":true,"description":"Public hint for the resource linked to a completed job result. Raw provider ids, provider URLs, signed URLs, private media URLs, and internal artifact keys are omitted.","required":["type","id","request_id","url","metadata"],"properties":{"type":{"type":"string","enum":["avatar_video"],"description":"Linked resource type."},"id":{"type":"string","nullable":true,"description":"Linked resource id when Sume can resolve it from resource storage or the public job result."},"request_id":{"type":"string","description":"Sume job/request id that produced this resource."},"url":{"type":"string","format":"uri","nullable":true,"description":"Public API URL for detailed resource readback when a resource id is available."},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoMetadataSummary"},{"type":"null"}],"description":"Lightweight metadata summary when available. Use the linked resource URL for detailed scenes and transcript readback."}}},"JobResultPayload":{"type":"object","nullable":true,"description":"Completed generation result data. Avatar Video jobs may include public-safe preview fields and `artifacts` entries for Sume-hosted intermediate scene or first-frame images. STT 1.0 jobs return `text` (and optional language fields / word timings) instead of media artifacts. TTS 1.0 (`text_to_speech`) jobs return `audio_url`, `model_id` (the engine), `voice` (`{ mode, id }`), `language`, `output_format` and the settings the audio was synthesized with (`generation_config`, `speed`). Raw provider source URLs, provider ids, queue URLs, signed URLs, and internal task keys are not part of the public result contract.","properties":{"source_audio":{"type":"string","enum":["kept","none","missing"],"description":"Sume Remix and Sume Remix Lite results: `kept` when the source video's sound is on the output, `none` when the source has no sound, `missing` when the sound could not be added and the clip is silent. Omitted for other job types."},"transcript_receipt":{"type":"object","additionalProperties":false,"description":"Server-owned TTS source-integrity proof. Required for LC acceptance and reuse. Count-only QA or a caller-supplied receipt cannot substitute for this proof.","required":["job_id","script_revision_id","sentence_ids","canonicalization_version","submitted_transcript_sha256","input_integrity"],"properties":{"job_id":{"type":"string"},"script_revision_id":{"type":"string"},"sentence_ids":{"type":"array","items":{"type":"string"}},"canonicalization_version":{"type":"string","enum":["nfc-lf-sentence-v1"]},"submitted_transcript_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"input_integrity":{"type":"string","enum":["source_bound"]}}},"generation_config":{"type":"object","nullable":true,"additionalProperties":true,"description":"TTS 1.0 results: the `generation_config` the audio was synthesized with (volume, speed, emotion), or null when none was sent. Omitted for other job types and on TTS jobs completed before this field shipped.","properties":{"volume":{"type":"number"},"speed":{"type":"number"},"emotion":{"type":"string"}}},"speed":{"type":"string","nullable":true,"description":"TTS 1.0 results: the deprecated `speed` enum the audio was synthesized with, or null when none was sent. Omitted for other job types and on TTS jobs completed before this field shipped."},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Representative public Sume-hosted Avatar Video preview image URL when available. For prompt scenes this is a mirrored generated first-frame or scene frame; for photo scenes this may be the normalized Sume-hosted scene image. Raw provider URLs are never returned."},"scene":{"type":"object","nullable":true,"required":["type","status","preview_image_url"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"]},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"]},"preview_image_url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri"}},"additionalProperties":false},"scene_previews":{"type":"array","items":{"$ref":"#/components/schemas/PublicAvatarVideoScenePreview"},"description":"Ordered public-safe Avatar Video scene preview metadata. Dialogue text, prompts, provider ids, and internal task keys are omitted."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicArtifact"}},"text":{"type":"string","description":"Transcript text for completed STT 1.0 jobs. Omitted for media generation jobs."},"language_code":{"type":"string","nullable":true,"description":"Detected or requested language code for STT 1.0 results when available."},"language_probability":{"type":"number","nullable":true,"description":"Provider language detection confidence for STT 1.0 when available."},"words":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"word":{"type":"string","description":"Transcribed token text."},"start":{"type":"number","description":"Token start offset in seconds from the audio start."},"end":{"type":"number","description":"Token end offset in seconds from the audio start."},"type":{"type":"string","description":"Provider token classification when supplied (for example `word` or `spacing`)."}}},"description":"Word-level timings for completed STT 1.0 jobs. Always present (possibly empty) on STT results; omitted for media generation jobs. Entries are ordered by `start`. Capped at 20000 entries — a 600s transcript stays well under that, and if the cap is ever reached the result also carries `words_truncated` and `words_total`."},"words_truncated":{"type":"boolean","description":"Present and `true` only when `words` was capped. Timings are never dropped silently."},"words_total":{"type":"integer","description":"Total timed tokens the provider returned, present only alongside `words_truncated`."},"segments":{"type":"array","description":"Sentence segments for STT 1.0 jobs submitted with `segmentation.mode: \"sentence\"`, omitted otherwise. Gapless and ordered: `segments[i].end == segments[i+1].start`. Time ranges over the submitted `audio_url` — no sliced files are produced, so the caller owns cutting talk-block audio.","items":{"type":"object","additionalProperties":true,"properties":{"index":{"type":"integer","description":"Zero-based segment index."},"text":{"type":"string","description":"Sentence text."},"start":{"type":"number","description":"Segment start in seconds from the audio start."},"end":{"type":"number","description":"Segment end in seconds from the audio start."},"duration_seconds":{"type":"number","description":"`end - start`, in seconds."}}}}},"additionalProperties":true},"PublicAvatarVideoScenePreviewReference":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"],"description":"Public scene input kind. Prompt text and dialogue are intentionally omitted."},"image_url":{"type":"string","format":"uri","description":"Public Sume-hosted normalized scene photo URL when the scene is photo-backed. External caller URLs and provider URLs are omitted."}},"additionalProperties":false},"PublicAvatarVideoScenePreviewSummary":{"type":"object","nullable":true,"required":["type","status","preview_image_url"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"]},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"],"description":"Provider-neutral preview readiness. `ready` means `preview_image_url` points to public Sume media."},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Public Sume-hosted preview image for the primary scene when available."},"image_url":{"type":"string","format":"uri","description":"Public Sume-hosted normalized scene photo URL when this summary represents a photo scene."}},"additionalProperties":false},"PublicAvatarVideoScenePreview":{"type":"object","required":["index","status","preview_image_url","scene"],"properties":{"index":{"type":"integer","minimum":0},"id":{"type":"string","description":"Optional caller-provided scene id when it is available from `video_inputs[]`."},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"]},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Public Sume-hosted preview image URL for this scene's first frame when available."},"scene":{"$ref":"#/components/schemas/PublicAvatarVideoScenePreviewReference"},"avatar_handle":{"type":"string","description":"Public avatar handle selected for this scene when provided. Avatar ids may be omitted when not public-safe."},"start_time_seconds":{"type":"number","minimum":0},"end_time_seconds":{"type":"number","minimum":0},"duration_seconds":{"type":"number","minimum":0}},"additionalProperties":false},"PublicAvatarVideoCaptions":{"type":"object","additionalProperties":false,"required":["enabled","style","language","status"],"description":"Public-safe inline captions summary for Avatar Video. When captions.enabled was requested (top-level or via package.captions), status progresses pending → ready on successful burn-in, or failed when the caption stage soft-fails after a successful clean avatar video (primary video_url remains the clean MP4 unless a later package stage succeeds). When status is failed, public_reason may carry a typed soft-fail code (for example script_alignment_mismatch, script_alignment_failed, empty_timed_words, caption_stage_failed). When clients supply captions.script_text (or package.captions.script_text), alignment mismatches soft-fail captions with that typed public_reason and do not burn STT wording — primary video_url stays the clean MP4. When script_text is omitted, Sume derives caption copy from the spoken script and may fall back to STT wording on alignment mismatch. Standalone POST /v1/video-captions still hard-fails alignment. Omitting captions or enabled:false yields null here and preserves clean-video behavior. Preview stills never burn captions; captions intent may be stored on preview create and applied only at generate-video. Inline captions require speakable script/video_inputs text and reject estimated duration above 60 seconds. Standalone POST /v1/video-captions remains unchanged and still requires video_captions:write; inline captions use avatar-video write scope only.","properties":{"enabled":{"type":"boolean"},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"]},"language":{"type":"string"},"status":{"type":"string","enum":["skipped","pending","ready","failed"]},"public_reason":{"type":"string","nullable":true,"description":"Typed soft-fail reason when status is failed. Omitted while pending/ready. Never includes script text, STT wording, or provider payloads."}}},"PublicAvatarVideoPackageSoundtrack":{"type":"object","additionalProperties":false,"required":["status","volume","audio_url"],"description":"Public-safe soundtrack summary for Avatar Video package post-production. When package.soundtrack.prompt was requested, Music 1.0 generates BGM; when package.soundtrack.audio_url was requested, the provided public HTTPS audio is mirrored and muxed with no Music call. While pending, BYO audio_url is echoed from the request so agents can confirm intent; prompt soundtrack stays null until ready. Mux runs after captions (when captions are also requested). Soft-fail keeps the furthest successful primary video_url (captioned when ready, else clean). When status is failed, public_reason carries a typed soft-fail code.","properties":{"status":{"type":"string","enum":["skipped","pending","ready","failed"]},"volume":{"type":"number","description":"Linear BGM volume used for mux (default 0.15)."},"audio_url":{"type":"string","format":"uri","nullable":true,"description":"BYO request audio_url while pending, or mirrored soundtrack URL after successful prep (Music 1.0 output or BYO mirror). Null for prompt soundtrack while pending, or after soft-fail before mirror."},"public_reason":{"type":"string","description":"Typed soft-fail reason when status is failed (for example soundtrack_unavailable, music_generation_failed, missing_music_audio). Omitted while pending/ready."}}},"PublicAvatarVideoPackageMux":{"type":"object","additionalProperties":false,"required":["status"],"description":"Public-safe mux stage summary. Mux ducks soundtrack under the captioned MP4 when captions succeeded, otherwise under the clean talking-head. Soft-fail preserves the furthest successful primary video_url (captioned when ready, else clean). When status is failed, public_reason carries a typed soft-fail code (often soundtrack_unavailable when soundtrack prep failed).","properties":{"status":{"type":"string","enum":["skipped","pending","ready","failed"]},"public_reason":{"type":"string","description":"Typed soft-fail reason when status is failed. Omitted while pending/ready."}}},"PublicAvatarVideoPackage":{"type":"object","additionalProperties":false,"required":["captions","soundtrack","mux"],"description":"Public-safe Avatar Video package post-production summary. When both captions and soundtrack are requested, server order is caption-on-clean then mux BGM under the captioned (or clean if captions skipped/soft-failed) MP4. Soft-fail keeps the furthest successful primary video_url: captioned when captions.status is ready, otherwise clean talking-head.","properties":{"captions":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoCaptions"},{"type":"null"}]},"soundtrack":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoPackageSoundtrack"},{"type":"null"}]},"mux":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoPackageMux"},{"type":"null"}]}}},"WebhookDelivery":{"type":"object","nullable":true,"required":["url","event_type","status","attempts","max_attempts","next_attempt_at","last_attempt_at","delivered_at","last_status_code","last_error","signature_version","signing_secret_fingerprint"],"properties":{"url":{"type":"string","format":"uri","nullable":true,"description":"The callback URL the job was created with. Null only when a Studio Agent turn on the job's thread reads a job another workspace member created: the delivery state is shown, the owner's endpoint is not. An API key always sees its own jobs' URL."},"event_type":{"type":"string","enum":["job.completed","job.failed","job.canceled"],"nullable":true},"status":{"type":"string","enum":["pending","delivering","delivered","retrying","failed","exhausted"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","format":"date-time","nullable":true},"last_attempt_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"last_status_code":{"type":"integer","nullable":true},"last_error":{"type":"string","nullable":true,"description":"Why the last attempt failed, or null. Also null when `url` is withheld, because the text can name the endpoint's host."},"signature_version":{"type":"string"},"signing_secret_fingerprint":{"type":"string","nullable":true,"description":"Non-reversible fingerprint of the signing secret the last attempt used, echoed on the delivery as `x-sume-webhook-secret-fingerprint`. Compare it with the fingerprint on `GET /v1/webhooks/signing-secret` to confirm your verifier holds the same secret, without either side quoting the secret. Null until an attempt has been made."},"manual_redeliveries":{"type":"integer","minimum":0,"description":"Count of partner-triggered redeliveries. Not one of the automatic `attempts` — a delivery that exhausted auto retries can still be poked."}}},"RunWebhookDelivery":{"type":"object","nullable":true,"description":"Delivery state for the run's `communication.webhook_url`, or null when the run was created without one.","required":["url","event_type","status","attempts","max_attempts","next_attempt_at","last_attempt_at","delivered_at","last_status_code","last_error","signature_version","signing_secret_fingerprint"],"properties":{"url":{"type":"string","format":"uri"},"event_type":{"type":"string","nullable":true,"description":"The `RunWebhookEvent.type` that will be sent, e.g. `format.run.terminal`. Null until delivery is armed."},"status":{"type":"string","enum":["not_armed","pending","retrying","delivered","failed","exhausted"],"description":"`not_armed` means the URL is stored but nothing is scheduled yet — the run is still running (or was canceled / skipped, which never arms a delivery). `pending`/`retrying` are in flight, `delivered` succeeded, and `failed`/`exhausted` gave up."},"attempts":{"type":"integer","minimum":0},"max_attempts":{"type":"integer","minimum":0},"next_attempt_at":{"type":"string","format":"date-time","nullable":true},"last_attempt_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"last_status_code":{"type":"integer","nullable":true,"description":"HTTP status your endpoint returned on the last attempt."},"last_error":{"type":"string","nullable":true,"description":"Sume-side transport error from the last attempt (timeout, connection failure, non-2xx status). Never your response body."},"signature_version":{"type":"string","nullable":true,"description":"Signature scheme used for `x-sume-webhook-signature`, e.g. `sume-v1`. Null until delivery is armed."},"signing_secret_fingerprint":{"type":"string","nullable":true,"description":"Non-reversible fingerprint of the signing secret the last attempt used, echoed on the delivery as `x-sume-webhook-secret-fingerprint`. Compare it with the fingerprint on `GET /v1/webhooks/signing-secret` to confirm your verifier holds the same secret, without either side quoting the secret. Null until an attempt has been made."},"manual_redeliveries":{"type":"integer","minimum":0,"description":"Count of partner-triggered redeliveries. Not one of the automatic `attempts` — a delivery that exhausted auto retries can still be poked."}}},"PublicDeveloperApiJobError":{"type":"object","nullable":true,"description":"Public-safe failure summary for failed or canceled jobs. Raw generation task ids, generation service URLs, signed URLs, request bodies, stack traces, secrets, and private database fields are omitted.","required":["category","stage","retryable","retry_after_seconds","public_reason","next_action"],"properties":{"code":{"type":"string","description":"Stable Sume error code retained for compatibility."},"message":{"type":"string","description":"Concise public-safe message. For provider generation failures this is the sanitized upstream reason (validation detail / reject message) when one was stored; generic wrappers like 'Generation failed.' are used only when no useful upstream text exists. Secrets, API keys, and URLs are stripped."},"category":{"type":"string","enum":["validation","auth","quota","queue","generation_unavailable","generation_rejected","generation_timeout","runtime_unavailable","worker_timeout","internal"]},"stage":{"type":"string","enum":["validation","queue","usage_reservation","generation_submit","generation_processing","video_caption_render","video_caption_source","audio_processing","usage_settlement","webhook_delivery","cancellation","internal"]},"retryable":{"type":"boolean","description":"Whether retrying the same request later is expected to help. Use with `retry_after_seconds` when present."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Public retry hint for transient failures. Null when Sume has no specific retry delay."},"public_reason":{"type":"string","description":"Machine-friendly public reason that SDKs, agents, and support tooling can group on safely. Examples include generation_rejected, image_content_rejected, and content_policy_rejected."},"next_action":{"type":"string","enum":["fix_input","simplify_script_text_or_omit","add_funds","retry_later","poll_status","inspect_events","contact_support","use_overlay_captions"]},"status":{"type":"string","nullable":true,"description":"Optional legacy/internal status hint retained when it is already public-safe."},"details":{"type":"object","additionalProperties":false,"description":"Optional public-safe structured details. For video caption script_text alignment failures this may include alignment_reason and word counts only — never script text, STT word text, or raw model payloads. For deterministic timeline ffmpeg graph failures this may include a sanitized ffmpeg_error diagnostic (no temp paths or argv), and for an undecodable timeline slot the failing segment_index (never the source URL). For a timeline source that answered 404/410 (public_reason source_not_found or bgm_source_not_found) this may include source_slot, source_status and source_host — the slot and the origin, still never the source URL, which the caller supplied and can look up from the slot. Provider generation failures may include a sanitized provider_error_message (the same upstream text as error.message), provider_error_type, and input_field — never keys, PEMs, or URLs.","properties":{"alignment_reason":{"type":"string","enum":["invalid_alignment_payload","empty_aligned_words","invalid_stt_span","overlapping_stt_spans","non_monotonic_timings","script_coverage_mismatch"]},"script_word_count":{"type":"integer","minimum":0},"stt_word_count":{"type":"integer","minimum":0},"ffmpeg_error":{"type":"string","description":"Sanitized ffmpeg diagnostic for deterministic timeline filtergraph failures. Never includes temp paths or argv."},"provider_error_type":{"type":"string","description":"Provider-reported error type identifier, e.g. file_download_error or value_error. Never a URL or payload."},"provider_error_message":{"type":"string","description":"Sanitized upstream/provider reason (validation detail or reject message). Secrets, API keys, and URLs are stripped."},"input_field":{"type":"string","description":"Request field the provider blamed, e.g. image_url or duration. Never the URL."},"segment_index":{"type":"integer","minimum":0,"description":"Timeline `video[]` index that failed, e.g. with public_reason invalid_video_source. The source URL itself is never returned."},"source_slot":{"type":"string","description":"Which timeline slot a missing source belongs to, with public_reason source_not_found or bgm_source_not_found: `video[N]`, `audio`, `audio.parts[N]` or `soundtrack`. A soundtrack 404 is bgm_source_not_found, not a missing clip."},"source_status":{"type":"integer","description":"HTTP status a missing timeline source answered with (404 or 410). Retrying the same URL will not help."},"source_host":{"type":"string","description":"Host of a missing timeline source, e.g. `media.sume.com`. Host only — never the path, query, or full URL."}}}},"example":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}},"PublicDeveloperApiJobUsageSummary":{"type":"object","nullable":true,"description":"Public-safe Sume usage summary for this job in credits, when a usage ledger row exists. Provider costs, ledger metadata, and idempotency keys are omitted.","required":["status","reserved_credits","captured_credits","refunded_credits","released_credits","final","updated_at"],"properties":{"status":{"type":"string","enum":["reserved","captured","refunded"]},"reserved_credits":{"type":"integer","minimum":0,"description":"Credits the job's reservation holds (or held)."},"captured_credits":{"type":"integer","minimum":0,"description":"Credits the wallet kept once the job settled; 0 until captured."},"refunded_credits":{"type":"integer","minimum":0,"description":"Credits given back when the job failed or was canceled."},"released_credits":{"type":"integer","minimum":0,"description":"Credits no longer held by the reservation after refund/release. Spendable balance restoration can differ when the original credit lot expires before release."},"reserved_usd_cents":{"type":"integer","minimum":0,"description":"`reserved_credits` in whole US cents, rounded up."},"captured_usd_cents":{"type":"integer","minimum":0,"description":"`captured_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":"integer","minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"released_usd_cents":{"type":"integer","minimum":0,"description":"`released_credits` in whole US cents, rounded up."},"final":{"type":"boolean","description":"True once the Sume usage reservation has been captured or released."},"updated_at":{"type":"string","format":"date-time"},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"PublicDeveloperApiJob":{"type":"object","required":["id","type","status","model","idempotency_key","communication_mode","created_at","updated_at","started_at","completed_at","canceled_at","auth_source","result","error","usage_summary","webhook_delivery"],"properties":{"transcript_receipt":{"type":"object","additionalProperties":false,"description":"Server-owned TTS source-integrity proof. Required for LC acceptance and reuse. Count-only QA or a caller-supplied receipt cannot substitute for this proof.","required":["job_id","script_revision_id","sentence_ids","canonicalization_version","submitted_transcript_sha256","input_integrity"],"properties":{"job_id":{"type":"string"},"script_revision_id":{"type":"string"},"sentence_ids":{"type":"array","items":{"type":"string"}},"canonicalization_version":{"type":"string","enum":["nfc-lf-sentence-v1"]},"submitted_transcript_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"input_integrity":{"type":"string","enum":["source_bound"]}}},"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"model":{"type":"string","nullable":true,"description":"Sume-owned public model id for this job when available. Internal provider model ids are not exposed."},"idempotency_key":{"type":"string","nullable":true,"description":"The `Idempotency-Key` this job was created with, or null when none was sent. This is the join column for recovery: list pages are newest-first, which is not the order you submitted in once a wave retries, so map your own key to `id` here rather than reading identity off array position."},"communication_mode":{"type":"string","enum":["async","sync","subscribe","webhook"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"canceled_at":{"type":"string","format":"date-time","nullable":true},"auth_source":{"type":"string","enum":["api_key"],"nullable":true,"description":"Non-identifying authentication source. API key ids and prefixes are intentionally omitted."},"input":{"type":"object","additionalProperties":true,"description":"How the job was made, for `image_generation`, `video_generation` and `music_generation` jobs: the prompt, settings and input media it ran with (for example `prompt`, `aspect_ratio`, `duration`, `resolution`, `num_images`, `image_urls`, `image_url`, `reference_image_urls`), exactly as the request stored them. `model` is the job's own field and is not repeated (an auto pick stays `sume/auto`); webhook, callback, wait and `metadata` fields are omitted. Absent on other job types. Send these back with the same `model` to make another one like it."},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Avatar Video preview image URL when available. Prompt scenes use a mirrored generated scene or first-frame image; photo scenes use the normalized Sume-hosted scene image. Null for other job types or before preview media exists."},"scene":{"type":"object","nullable":true,"required":["type","status","preview_image_url"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"]},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"]},"preview_image_url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri"}},"additionalProperties":false},"scene_previews":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicAvatarVideoScenePreview"},"description":"Public-safe Avatar Video scene preview metadata for status polling. Raw prompt text, dialogue, provider URLs, provider task ids, and internal task keys are omitted."},"result":{"$ref":"#/components/schemas/JobResultPayload"},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"},"usage_summary":{"$ref":"#/components/schemas/PublicDeveloperApiJobUsageSummary"},"webhook_delivery":{"$ref":"#/components/schemas/WebhookDelivery"}}},"JobsListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["jobs"],"properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}},"next_cursor":{"type":"string","description":"Opaque cursor for the next page, present only when more jobs remain. Pass it back as `starting_after`. Absent on the last page, which is the loop terminator — do not synthesize one from the final job."}}}}},"AvatarListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["avatars"],"properties":{"avatars":{"type":"array","items":{"$ref":"#/components/schemas/PublicResourceSummary"}}}}}},"AvatarCatalogSearchRequest":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"Optional text query matched against public-safe avatar metadata and display fields. When present, default mode is search; when omitted/empty, default mode is explore."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"mode":{"type":"string","enum":["search","explore"],"description":"search keeps relevance-first deterministic ranking (unless shuffle). explore applies seeded diversity jitter for browse. Defaults to search when query is present, otherwise explore."},"seed":{"type":"string","minLength":1,"maxLength":128,"description":"Opaque client/session seed. Used for explore/shuffle jitter so identical seeds stay stable. Search without shuffle remains deterministic even when seed is omitted."},"shuffle":{"type":"boolean","default":false,"description":"When true, applies seeded explore-style jitter even in search mode. Always seeded (client seed or workspace/day hash); never unseeded Math.random."},"diversity":{"type":"number","minimum":0,"maximum":1,"description":"0..1 attribute MMR diversity knob. Higher values increase diversity. Maps to MMR lambda as (1 - diversity). Defaults: 0.2 in search mode, 0.5 in explore mode."},"min_results":{"type":"integer","minimum":1,"maximum":100,"default":5,"description":"Thin-result threshold used when auto_expand is enabled. Secondary filters may relax until at least this many results are available when possible."},"auto_expand":{"type":"boolean","default":true,"description":"When true (default), thin results trigger a labeled relaxation cascade (soft text, then drop product_category, then best_for). Language/visibility/ownership stay sacred. Set false to preserve strict filter/token drop behavior."},"dedupe":{"type":"string","enum":["off","source","default"],"default":"default","description":"Source-identity exact dedupe. default and source collapse candidates that share a normalized still/photo URL before attribute MMR. off disables collapse (debug). Phase A does not cover prompt-only near-clones."},"filters":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["processing","ready","failed","archived"],"default":"ready"},"visibility":{"type":"string","enum":["public","private"],"description":"Public system avatars are available to all authenticated callers; private results are limited to the authenticated owner workspace."},"product_category":{"type":"string"},"product_categories":{"type":"array","items":{"type":"string"},"maxItems":20},"use_case":{"type":"string"},"best_for":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":20}]},"language":{"type":"string"}}}}},"PublicAvatarCatalogSearchResult":{"type":"object","description":"Public avatar result with text-search score metadata. Keyword search without shuffle stays deterministic; explore/shuffle may apply seeded jitter for browse diversity. Raw provider payloads are omitted.","additionalProperties":true,"required":["id","handle","metadata","search_score","search_reasons"],"properties":{"id":{"type":"string"},"handle":{"type":"string"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarProfileMetadata"},{"type":"null"}]},"search_score":{"type":"number"},"search_reasons":{"type":"array","items":{"type":"string"}}}},"AvatarCatalogSearchResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["avatars","count","query","filters"],"properties":{"avatars":{"type":"array","items":{"$ref":"#/components/schemas/PublicAvatarCatalogSearchResult"}},"count":{"type":"integer"},"query":{"type":["null","string"]},"filters":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["search","explore"]},"seed_used":{"type":["null","string"]},"relaxed_filters":{"type":"array","items":{"type":"string"},"description":"Filters or matching rules relaxed by auto_expand. Empty when no relaxation occurred."},"candidate_count":{"type":"integer","description":"Number of avatar candidates loaded before scoring (paginated store list, up to 1000)."},"diversity":{"type":"object","additionalProperties":false,"properties":{"lambda":{"type":"number"},"strategy":{"type":"string","enum":["attribute_mmr","attribute_mmr+source_dedupe"],"description":"Ranking/diversity strategy actually applied. attribute_mmr reranks lexical scores with facet-overlap MMR; +source_dedupe is appended when source-identity collapse ran."},"source_dedupe":{"type":"object","additionalProperties":false,"description":"Present when source-identity dedupe ran (dedupe default/source). collapsed is rows dropped; clusters is multi-avatar identity groups.","properties":{"collapsed":{"type":"integer","minimum":0},"clusters":{"type":"integer","minimum":0}}}}}}}}},"AvatarVideoListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["avatar_videos"],"properties":{"avatar_videos":{"type":"array","items":{"$ref":"#/components/schemas/PublicResourceSummary"}}}}}},"JobResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"JobCancelResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job_id","status","canceled","idempotency_hit","status_url","result_url","cancellation","job"],"properties":{"request_id":{"type":"string"},"job_id":{"type":"string"},"status":{"type":"string","enum":["CANCELED"]},"canceled":{"type":"boolean"},"idempotency_hit":{"type":"boolean","description":"True when the job was already canceled before this request."},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"cancellation":{"type":"object","description":"Public cancellation outcome. Sume accepts cancellation only before external generation work starts.","required":["supported","requested","message"],"properties":{"supported":{"type":"boolean"},"requested":{"type":"boolean"},"message":{"type":"string"}}},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"PublicDeveloperApiJobEvent":{"type":"object","required":["id","type","source","status","message","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["job.created","job.queued","job.started","generation.submitted","job.completed","job.failed","job.canceled","webhook.delivery"]},"source":{"type":"string","enum":["sume","webhook"]},"status":{"type":"string","enum":["info","pending","processing","succeeded","failed","canceled","retrying"]},"message":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Sanitized event details. Terminal and generation-failure events may include `error` using PublicDeveloperApiJobError. Raw generation service URLs, task ids, callback signatures, API-key metadata, idempotency keys, and secrets are intentionally omitted."}}},"JobEventsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job_id","events"],"properties":{"request_id":{"type":"string"},"job_id":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/PublicDeveloperApiJobEvent"}}}}}},"PublicGenerationLimits":{"type":"object","nullable":true,"description":"Provider-neutral Sume generation admission limits for the authenticated workspace. Concurrency follows the funds added to the workspace in the past 28 days (2, 10, 20 or 40 at once; the Rate limits guide lists the steps). open.sume.com keys count running and queued together, so their queued_jobs_limit is 0. Active admin overrides can raise concurrency_limit without changing the subscription plan. concurrency_limit is the processing cap shown by the dashboard Concurrency tab. wave_size_hint is a submission-wave hint only, not a concurrency limit; size in-flight work from the processing cap and live active/queued counts, never from wave_size_hint or plan_concurrency_limit.","required":["tier","plan_id","limit_source","purchased_credits_last_4_weeks","purchased_concurrency_limit","purchased_queued_jobs_limit","plan_concurrency_limit","plan_queued_jobs_limit","concurrency_limit","queued_jobs_limit","admin_override_expires_at","accepted_generation_jobs_limit","active_generation_jobs","queued_generation_jobs","accepted_generation_jobs","queue_capacity_remaining","wave_size_hint"],"properties":{"tier":{"type":"string","enum":["free","pro","startup","scale","enterprise","tier_10","tier_100","tier_500","tier_1000"]},"plan_id":{"type":"string","enum":["free","pro","startup","scale","enterprise"],"description":"Active subscription plan id, or free when none. It does not set concurrency."},"limit_source":{"type":"string","enum":["plan","admin_override"],"description":"Whether concurrency_limit comes from the workspace's top-up grade (plan) or an active admin override; this does not turn wave_size_hint into a limit."},"purchased_credits_last_4_weeks":{"type":"integer","minimum":0,"description":"Credits topped up in the last 28 days. They set purchased_concurrency_limit."},"purchased_concurrency_limit":{"type":"integer","minimum":1,"description":"Concurrent generation limit the last 28 days of top-ups reach, before any admin override."},"purchased_queued_jobs_limit":{"type":"integer","minimum":1,"description":"Queued generation capacity for purchased_concurrency_limit, before any admin override."},"plan_concurrency_limit":{"type":"integer","minimum":1,"description":"Deprecated alias of purchased_concurrency_limit. The subscription plan no longer sets concurrency."},"plan_queued_jobs_limit":{"type":"integer","minimum":1,"description":"Deprecated alias of purchased_queued_jobs_limit."},"concurrency_limit":{"type":"integer","minimum":1,"description":"Effective maximum paid generation jobs in processing for this workspace: the processing cap shown by the dashboard Concurrency tab, including any admin override. Size new in-flight work from max(0, concurrency_limit - active_generation_jobs - queued_generation_jobs), capped by queue_capacity_remaining; wait and refresh when no headroom remains."},"queued_jobs_limit":{"type":"integer","minimum":0,"description":"Effective additional accepted generation jobs beyond the concurrency slots."},"admin_override_expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Expiry timestamp for an active admin override. Null when no effective admin override is raising the limit or the override does not expire."},"accepted_generation_jobs_limit":{"type":"integer","minimum":1,"description":"concurrency_limit + queued_jobs_limit."},"active_generation_jobs":{"type":"integer","minimum":0,"description":"Current processing generation jobs in this workspace."},"queued_generation_jobs":{"type":"integer","minimum":0,"description":"Current queued generation jobs in this workspace."},"accepted_generation_jobs":{"type":"integer","minimum":0,"description":"active_generation_jobs + queued_generation_jobs."},"queue_capacity_remaining":{"type":"integer","minimum":0,"description":"Remaining pending-work slots before Sume returns queue_full: the queued-job budget plus idle concurrency seats. Processing beyond the concurrency limit never reduces it below the queued-job budget."},"wave_size_hint":{"type":"integer","minimum":1,"description":"Submission-wave hint only: max(1, floor(queue_capacity_remaining * 0.75)). Not a concurrency limit, override, or processing width. Includes queue slots and may exceed concurrency_limit; never size in-flight work from this hint. Example: concurrency_limit=100, queued_jobs_limit=500, queue_capacity_remaining=600, wave_size_hint=450 still means concurrency=100. Use concurrency_limit and live active_generation_jobs/queued_generation_jobs for in-flight work. When queue_capacity_remaining is 0, wait rather than submit even though this hint is 1."}}},"SubmitJobResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage"],"properties":{"request_id":{"type":"string"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"SumeImageGenerationRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"description":"Text prompt for Sume Image 1.0. Provider model ids are selected by Sume and are not accepted in this schema. When avatar_id or avatar_handle is set, Sume wraps this creative brief with identity-preserving still-ad instructions."},"avatar_id":{"type":"string","minLength":1,"description":"Optional ready avatar id for face-in-still ads. Sume resolves the identity still (idle_still → avatar_base / preview) and injects it as Image 1 in the edit path. Use with optional product image_urls. Talking-head / lip-sync remains Avatar Video Stage P — not this field."},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Optional ready avatar handle for face-in-still ads (same handle grammar as Avatar APIs). Prefer avatars_search / avatars_get first. When both avatar_id and avatar_handle are set, they must resolve to the same avatar."},"image_urls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"description":"Optional public HTTPS reference/edit image URLs. When present, Sume routes internally to the image edit/reference flow. With avatar_id/avatar_handle, product/other refs are appended after the resolved avatar identity still (total max 10)."},"input_urls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"deprecated":true,"description":"Alias for image_urls. Prefer image_urls."},"mask_image_url":{"type":"string","format":"uri","description":"Optional public HTTPS mask image URL for edit requests."},"aspect_ratio":{"type":"string","enum":["auto","1:1","9:16","16:9","4:3","3:4","5:4","9:8","4:5"],"description":"Sume aspect-ratio hint. On edit/i2i with image_urls, prefer \"auto\" to match the reference; omit is not auto. If image_size is also provided, image_size takes precedence. `4:5` is Instagram portrait (1080×1350), not 4:3; it expands to legal gpt-image-2 custom pixels (1024×1280). `5:4` and `9:8` also expand to custom pixels."},"image_size":{"description":"Named preset, custom {width,height}, or WIDTHxHEIGHT. Wins over aspect_ratio. Custom sizes are validated against the gpt-image-2 pixel box; named presets are not.","oneOf":[{"type":"string","enum":["auto","square","square_hd","portrait_16_9","landscape_16_9","landscape_4_3","portrait_4_3"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1}},"description":"Custom gpt-image-2 size. Both edges multiples of 16, max edge 3840, aspect ≤3:1, total pixels 655,360–8,294,400. Canvas 720×640 is below min; 9:8 use 864×768."},{"type":"string","pattern":"^[0-9]+[x×][0-9]+$","description":"OpenAI-style WIDTHxHEIGHT custom size, same pixel box as the object form."}]},"quality":{"type":"string","enum":["low","medium","high"],"description":"Image quality tier. Defaults to `low` when omitted. Escalate to `medium` or `high` for final assets, dense text, product packaging, or when the user asks for max quality."},"num_images":{"type":"integer","minimum":1,"maximum":4},"n":{"type":"integer","minimum":1,"maximum":4,"deprecated":true,"description":"Alias for num_images. Prefer num_images."},"output_format":{"type":"string","enum":["png","jpeg","jpg","webp"]},"format":{"type":"string","enum":["png","jpeg","jpg","webp"],"deprecated":true,"description":"Alias for output_format. Prefer output_format."},"transparency":{"type":"boolean","description":"When true, generate then remove background (Sume RMBG 1.0) per output image and return cutout PNG only. Default false (opaque/normal). JPEG output is rejected when true; omit format to get PNG. Bills image generation plus remove-background per image in one reservation."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeImageRouterGenerationRequest":{"type":"object","additionalProperties":false,"required":["model","prompt"],"properties":{"model":{"type":"string","enum":["higgsfield-soul","gpt-image-2.5","gpt-image-2.5-sunburst","gpt-image-2","nano-banana-2.1","nano-banana-pro","seedream-5-lite","seedream-4-5-edit","grok-image","seedream-v4","qwen-image","flux-2-pro","flux-2-flex","ideogram-v3","recraft-v4","qwen-image-max","qwen-image-layered","qwen-image-angles","ideogram-v4.5","nano-banana","flux-kontext-max","wan-2.2","recraft-v4.1","seedream-5-flash","z-image","flux-2-max","kling-image-o1","seedream-5-pro","higgsfield-soul-standard","higgsfield-soul-cinema","grok-imagine-2","recraft-v4.1-utility","kling-image-3","higgsfield-ai-influencer","higgsfield-ads-studio","nano-banana-2"],"description":"Required Image Router catalog model id (pass-through). Not accepted on Image 1.0. A retired id (`nano-banana-2`) runs as its successor (`nano-banana-2.1`)."},"prompt":{"type":"string","minLength":1,"description":"Text prompt for the selected Image Router model."},"image_urls":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","format":"uri"},"description":"Optional reference/edit image URLs. Rejected for text-to-image-only models."},"input_urls":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","format":"uri"},"description":"Alias for image_urls."},"background":{"type":"string","enum":["auto","transparent","opaque"],"description":"GPT Image 2.5 Flare and Sunburst only."},"mask_url":{"type":"string","format":"uri","description":"Optional edit mask URL."},"mask_image_url":{"type":"string","format":"uri","description":"Optional mask URL for gpt-image-2 edit."},"aspect_ratio":{"type":"string","enum":["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","9:8","1:2","2:1","1:3","3:1","1:4","4:1","1:8","8:1","9:21","21:9","10:16","16:10","20:9","19.5:9","9:19.5","9:20","6:10","14:10","10:14"],"description":"Optional. Per-model native catalog — 4:5 is Instagram portrait, not 4:3. On edit/i2i with image_urls, prefer \"auto\" to match the reference; omit is not auto."},"image_size":{"description":"Named preset, custom {width,height}, or WIDTHxHEIGHT. Wins over aspect_ratio. Custom sizes are validated against the gpt-image-2 pixel box; named presets are not.","oneOf":[{"type":"string","enum":["square","square_hd","portrait_16_9","landscape_16_9","landscape_4_3","portrait_4_3","auto","auto_2K","auto_3K","auto_4K"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1}},"description":"Custom gpt-image-2 size. Both edges multiples of 16, max edge 3840, aspect ≤3:1, total pixels 655,360–8,294,400. Canvas 720×640 is below min; 9:8 use 864×768."},{"type":"string","pattern":"^[0-9]+[x×][0-9]+$","description":"OpenAI-style WIDTHxHEIGHT custom size, same pixel box as the object form."}]},"quality":{"type":"string","description":"Model-specific quality hint (gpt-image-2: low|medium|high; GPT Image 2.5 Flare and Sunburst: auto|low|medium|high|xhigh|max; ideogram-v3: TURBO|BALANCED|QUALITY; ideogram-v4.5: low|medium|high, default medium)."},"resolution":{"type":"string","enum":["0.5K","1K","2K","4K","720p","1080p"],"description":"Model-specific: nano-banana uses the K tiers; ideogram-v4.5 accepts 1K or 2K; Higgsfield Soul accepts 720p or 1080p."},"rendering_speed":{"type":"string","enum":["TURBO","BALANCED","QUALITY"]},"n":{"type":"integer","minimum":1,"maximum":10,"deprecated":true,"description":"Alias for num_images. Prefer num_images."},"num_images":{"type":"integer","minimum":1,"maximum":10,"description":"Images to make: 1 to 4. `qwen-image-layered` takes 2 to 10 here, one layer each."},"output_format":{"type":"string","enum":["png","jpeg","jpg","webp"]},"format":{"type":"string","enum":["png","jpeg","jpg","webp"],"deprecated":true},"model_params":{"type":"object","additionalProperties":true,"description":"Empty allowlist in v1; omit or send {}. `higgsfield-ai-influencer` takes `tier` (`normal`, `freak` or `total`) and `selection` (a group id to up to 4 option ids)."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"ImageRouterCatalogItem":{"type":"object","additionalProperties":false,"required":["id","name","modality","routing","capabilities","pricing","constraints"],"properties":{"id":{"type":"string","enum":["higgsfield-soul","gpt-image-2.5","gpt-image-2.5-sunburst","gpt-image-2","nano-banana-2.1","nano-banana-pro","seedream-5-lite","seedream-4-5-edit","grok-image","seedream-v4","qwen-image","flux-2-pro","flux-2-flex","ideogram-v3","recraft-v4","qwen-image-max","qwen-image-layered","qwen-image-angles","ideogram-v4.5","nano-banana","flux-kontext-max","wan-2.2","recraft-v4.1","seedream-5-flash","z-image","flux-2-max","kling-image-o1","seedream-5-pro","higgsfield-soul-standard","higgsfield-soul-cinema","grok-imagine-2","recraft-v4.1-utility","kling-image-3","higgsfield-ai-influencer","higgsfield-ads-studio"]},"name":{"type":"string"},"modality":{"type":"string","enum":["image"]},"routing":{"type":"string","enum":["pass_through"]},"capabilities":{"type":"object","additionalProperties":false,"required":["text_to_image","image_edit","aspect_ratios","resolutions","qualities","max_images","output_formats"],"properties":{"text_to_image":{"type":"boolean"},"image_edit":{"type":"boolean"},"aspect_ratios":{"type":"array","items":{"type":"string"}},"resolutions":{"type":"array","items":{"type":"string"}},"qualities":{"type":"array","items":{"type":"string"}},"max_images":{"type":"integer"},"output_formats":{"type":"array","items":{"type":"string"}}}},"pricing":{"type":"object","additionalProperties":false,"description":"Credits per output image on this model (two decimals, rounded up). A request is charged its whole total once, rounded up.","required":["basis","credits_per_image"],"properties":{"basis":{"type":"string","enum":["per_image"]},"credits_per_image":{"type":"number","minimum":0},"usd_per_image":{"type":"string","pattern":"^\\d+\\.\\d{4,}$","description":"On a model Open sells: the cheapest option's rate in US dollars per image."},"usd_options":{"type":"array","description":"On a model open.sume.com sells: each option's rate in US dollars per unit (Open's own decimal string), the price www charges for it. The figures to quote to a person. Absent on a model Open does not sell; dry_run gives that model's charge.","items":{"type":"object","additionalProperties":false,"required":["label","usd"],"properties":{"label":{"type":"string"},"resolution":{"type":"string"},"audio":{"type":"boolean"},"quality":{"type":"string"},"usd":{"type":"string","pattern":"^\\d+\\.\\d{4,}$"}}}}}},"constraints":{"type":"array","items":{"type":"string"}}}},"ImageRouterModelsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/ImageRouterCatalogItem"}}}}}},"ImageRouterModelResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"$ref":"#/components/schemas/ImageRouterCatalogItem"}}}}},"SumeImagesGenerationRequest":{"type":"object","additionalProperties":false,"required":["model","prompt"],"properties":{"model":{"type":"string","enum":["higgsfield/soul","openai/gpt-image-2","openai/gpt-image-2.5","openai/gpt-image-2.5-sunburst","google/nano-banana-2.1","google/nano-banana-pro","bytedance-seed/seedream-5-lite","bytedance-seed/seedream-4.5","bytedance-seed/seedream-4","x-ai/grok-image","qwen/qwen-image","qwen/qwen-image-max","qwen/qwen-image-layered","qwen/qwen-image-angles","black-forest-labs/flux.2-pro","black-forest-labs/flux.2-flex","ideogram/ideogram-v3","recraft/recraft-v4","ideogram/ideogram-v4.5","google/nano-banana","black-forest-labs/flux-kontext-max","alibaba/wan-2.2","recraft/recraft-v4.1","bytedance-seed/seedream-5-flash","alibaba/z-image","black-forest-labs/flux.2-max","higgsfield/soul-standard","higgsfield/soul-cinema","bytedance-seed/seedream-5-pro","x-ai/grok-imagine-2","recraft/recraft-v4.1-utility","kwaivgi/kling-image-o1","sume/image-1.0","sume/auto","higgsfield-soul","gpt-image-2.5","gpt-image-2.5-sunburst","gpt-image-2","nano-banana-2.1","nano-banana-pro","seedream-5-lite","seedream-4-5-edit","grok-image","seedream-v4","qwen-image","flux-2-pro","flux-2-flex","ideogram-v3","recraft-v4","qwen-image-max","qwen-image-layered","qwen-image-angles","ideogram-v4.5","nano-banana","flux-kontext-max","wan-2.2","recraft-v4.1","seedream-5-flash","z-image","flux-2-max","kling-image-o1","seedream-5-pro","higgsfield-soul-standard","higgsfield-soul-cinema","grok-imagine-2","recraft-v4.1-utility","kling-image-3","higgsfield-ai-influencer","higgsfield-ads-studio","google/nano-banana-2","nano-banana-2"],"description":"Model slug from GET /v1/images/models. Legacy bare Image Router ids are also accepted. A retired model (`google/nano-banana-2`) runs as its successor (`google/nano-banana-2.1`). `sume/auto` lets Sume pick without disclosing the family."},"prompt":{"type":"string","minLength":1,"description":"Text description of the desired image."},"n":{"type":"integer","minimum":1,"maximum":10,"description":"Number of images to generate. Per-model ceilings come from the catalog `n` range descriptor."},"resolution":{"type":"string","enum":["512","1K","2K","4K","720p","1080p","0.5K"],"description":"Resolution tier. `0.5K` is accepted as a legacy alias for `512`."},"aspect_ratio":{"type":"string","enum":["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","9:8","1:2","2:1","1:3","3:1","1:4","4:1","1:8","8:1","9:21","21:9","10:16","16:10","20:9","19.5:9","9:19.5","9:20","6:10","14:10","10:14"],"description":"Normalized aspect ratio. Per-model catalog — 4:5 is Instagram portrait (1080×1350), not 4:3. On edit / image-to-image, prefer \"auto\" to match the reference; omitting the field is not auto. gpt-image-2 also accepts `5:4` and `9:8` (catalog-gated)."},"image_size":{"description":"Named preset, custom {width,height}, or WIDTHxHEIGHT. Wins over aspect_ratio. Custom sizes are validated against the gpt-image-2 pixel box; named presets are not.","oneOf":[{"type":"string","enum":["auto","square","square_hd","portrait_16_9","landscape_16_9","landscape_4_3","portrait_4_3"]},{"type":"object","additionalProperties":false,"required":["width","height"],"properties":{"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1}},"description":"Custom gpt-image-2 size. Both edges multiples of 16, max edge 3840, aspect ≤3:1, total pixels 655,360–8,294,400. Canvas 720×640 is below min; 9:8 use 864×768."},{"type":"string","pattern":"^[0-9]+[x×][0-9]+$","description":"OpenAI-style WIDTHxHEIGHT custom size, same pixel box as the object form."}]},"size":{"type":"string","description":"Shorthand for a resolution tier (`512`, `1K`, `2K`, `4K`). Do not put custom pixels here; use `image_size`."},"quality":{"type":"string","enum":["auto","low","medium","high","xhigh","max"],"description":"Quality tier. Models that expose a provider-specific vocabulary are mapped from these words."},"output_format":{"type":"string","enum":["png","jpeg","webp","svg"]},"mask_url":{"type":"string","format":"uri","description":"Optional mask URL for GPT Image 2.5 Flare and Sunburst editing."},"background":{"type":"string","enum":["auto","transparent","opaque"],"description":"Supported by GPT Image 2.5 Flare and Sunburst."},"output_compression":{"type":"integer","minimum":0,"maximum":100,"description":"Not served in v1; no model advertises this parameter."},"seed":{"type":"integer","description":"Not served in v1; no model advertises this parameter."},"stream":{"type":"boolean","description":"Native SSE streaming is not available yet; `true` returns 400 streaming_not_supported."},"input_references":{"type":"array","minItems":1,"maxItems":16,"description":"Reference images for image-to-image. Rejected by text-to-image-only models.","items":{"type":"object","additionalProperties":false,"required":["type","image_url"],"properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"provider":{"type":"object","additionalProperties":false,"description":"Provider routing. Sume publishes a single `sume` endpoint per model in v1, so pins accept only `sume` and the remaining fields are inert.","properties":{"only":{"type":"array","items":{"type":"string"}},"order":{"type":"array","items":{"type":"string"}},"ignore":{"type":"array","items":{"type":"string"}},"sort":{},"allow_fallbacks":{"type":"boolean"},"options":{"type":"object","additionalProperties":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"ImageModelListItem":{"type":"object","additionalProperties":false,"required":["id","name","description","created","architecture","supported_parameters","supports_streaming","endpoints"],"properties":{"id":{"type":"string","enum":["higgsfield/soul","openai/gpt-image-2","openai/gpt-image-2.5","openai/gpt-image-2.5-sunburst","google/nano-banana-2.1","google/nano-banana-pro","bytedance-seed/seedream-5-lite","bytedance-seed/seedream-4.5","bytedance-seed/seedream-4","x-ai/grok-image","qwen/qwen-image","qwen/qwen-image-max","qwen/qwen-image-layered","qwen/qwen-image-angles","black-forest-labs/flux.2-pro","black-forest-labs/flux.2-flex","ideogram/ideogram-v3","recraft/recraft-v4","ideogram/ideogram-v4.5","google/nano-banana","black-forest-labs/flux-kontext-max","alibaba/wan-2.2","recraft/recraft-v4.1","bytedance-seed/seedream-5-flash","alibaba/z-image","black-forest-labs/flux.2-max","higgsfield/soul-standard","higgsfield/soul-cinema","bytedance-seed/seedream-5-pro","x-ai/grok-imagine-2","recraft/recraft-v4.1-utility","kwaivgi/kling-image-o1"]},"name":{"type":"string"},"description":{"type":"string"},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the model was published."},"architecture":{"type":"object","additionalProperties":false,"required":["input_modalities","output_modalities"],"properties":{"input_modalities":{"type":"array","items":{"type":"string"}},"output_modalities":{"type":"array","items":{"type":"string"}}}},"supported_parameters":{"type":"object","additionalProperties":{"type":"object","description":"Capability descriptor: `enum` with values, `range` with min/max, or `boolean` for presence-only support.","required":["type"],"properties":{"type":{"type":"string","enum":["enum","range","boolean"]},"values":{"type":"array","items":{"type":"string"}},"min":{"type":"number"},"max":{"type":"number"}}},"description":"Capability descriptors keyed by request parameter. A parameter absent here is rejected with unsupported_parameter."},"supports_streaming":{"type":"boolean"},"endpoints":{"type":"string","description":"Relative URL to the full per-endpoint records for this model."}}},"ImageModelsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ImageModelListItem"}}}},"ImageModelEndpointsResponse":{"type":"object","required":["id","endpoints"],"properties":{"id":{"type":"string","enum":["higgsfield/soul","openai/gpt-image-2","openai/gpt-image-2.5","openai/gpt-image-2.5-sunburst","google/nano-banana-2.1","google/nano-banana-pro","bytedance-seed/seedream-5-lite","bytedance-seed/seedream-4.5","bytedance-seed/seedream-4","x-ai/grok-image","qwen/qwen-image","qwen/qwen-image-max","qwen/qwen-image-layered","qwen/qwen-image-angles","black-forest-labs/flux.2-pro","black-forest-labs/flux.2-flex","ideogram/ideogram-v3","recraft/recraft-v4","ideogram/ideogram-v4.5","google/nano-banana","black-forest-labs/flux-kontext-max","alibaba/wan-2.2","recraft/recraft-v4.1","bytedance-seed/seedream-5-flash","alibaba/z-image","black-forest-labs/flux.2-max","higgsfield/soul-standard","higgsfield/soul-cinema","bytedance-seed/seedream-5-pro","x-ai/grok-imagine-2","recraft/recraft-v4.1-utility","kwaivgi/kling-image-o1"]},"endpoints":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["provider_name","provider_slug","provider_tag","supported_parameters","allowed_passthrough_parameters","supports_streaming","pricing"],"properties":{"provider_name":{"type":"string"},"provider_slug":{"type":"string"},"provider_tag":{"type":"string"},"supported_parameters":{"type":"object","additionalProperties":{"type":"object","description":"Capability descriptor: `enum` with values, `range` with min/max, or `boolean` for presence-only support.","required":["type"],"properties":{"type":{"type":"string","enum":["enum","range","boolean"]},"values":{"type":"array","items":{"type":"string"}},"min":{"type":"number"},"max":{"type":"number"}}},"description":"Capability descriptors keyed by request parameter. A parameter absent here is rejected with unsupported_parameter."},"allowed_passthrough_parameters":{"type":"array","items":{"type":"string"}},"supports_streaming":{"type":"boolean"},"pricing":{"type":"array","description":"Billable lines. `credits` is what the caller is charged per unit (two decimals, rounded up); a request is charged its whole total once, rounded up.","items":{"type":"object","additionalProperties":false,"required":["billable","unit","credits"],"properties":{"billable":{"type":"string"},"unit":{"type":"string"},"credits":{"type":"number","minimum":0}}}}}}}}},"ImageGenerationResponse":{"type":"object","required":["id","created","data","usage"],"properties":{"id":{"type":"string","description":"The Sume job id. The same job stays readable at GET /v1/jobs/{id}/result, and a retry with the same Idempotency-Key names it again."},"created":{"type":"integer"},"model":{"type":"string","description":"The requested model, echoed verbatim. `sume/auto` stays `sume/auto`."},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["url","media_type"],"properties":{"url":{"type":"string","format":"uri","description":"Sume-hosted image URL. Sume returns URLs rather than `b64_json`."},"media_type":{"type":"string"}}}},"usage":{"type":"object","additionalProperties":false,"required":["prompt_tokens","completion_tokens","total_tokens","credits"],"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"credits":{"type":"integer","minimum":0,"description":"Credits this generation is charged."}}}}},"SumeMusicGenerationRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"description":"Sume Music 1.0 text-to-music request. Prompt-driven only — do not send duration or duration_seconds (rejected as unrecognized). Provider model ids are selected by Sume.","properties":{"prompt":{"type":"string","minLength":1,"maxLength":5000,"description":"Text prompt for Sume Music 1.0. Write a per-scene music brief: emotion, genre, a BPM number, key/mode, lead instruments with texture, one named arc moment, era/production, then \"Instrumental, no vocals.\" Provider model ids are selected by Sume and are not accepted in this schema. Do not include duration or duration_seconds."},"negative_prompt":{"type":"string","default":"","description":"Not supported by Music 1.0 / Lyria 3. Omit the field or send an empty string. Non-empty values are rejected with public_reason=negative_prompt_unsupported. Put exclusions (no vocals, no spoken word, etc.) into the positive prompt instead."},"image_url":{"type":"string","format":"uri","nullable":true,"description":"Optional public HTTPS image URL used as a visual conditioning input; use the accepted scene still when appropriate. Null clears the image input."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeSttTranscribeRequest":{"type":"object","additionalProperties":false,"required":["audio_url"],"description":"Sume STT 1.0 speech-to-text request. Provide a public HTTPS audio_url. Optional language_code; omit for auto-detect. Optional duration_seconds (1–600) does not set the price: Sume reads the audio's length from the file and bills every started minute (an unreadable file is billed 10 minutes). Word timings are always returned, so there is no flag to enable them; send segmentation to also get sentence segments. Provider knobs such as diarize and tag_audio_events are fixed server-side.","properties":{"audio_url":{"type":"string","format":"uri","description":"Public HTTPS audio URL to transcribe. Prefer a Sume media / attachment URL."},"segmentation":{"type":"object","additionalProperties":false,"required":["mode"],"description":"Optional sentence segmentation derived from the returned word timings. Fails closed with a typed error if the provider returns no timed words.","properties":{"mode":{"type":"string","enum":["sentence"],"description":"Group words into sentences on terminal punctuation, splitting unpunctuated runs on silence."},"boundary_lead_ms":{"type":"integer","minimum":0,"maximum":500,"default":70,"description":"Milliseconds of lead carried past a sentence's last word before the next segment starts. Same rule and default as `sume/tts-1.0`."}}},"language_code":{"type":"string","minLength":2,"maxLength":16,"description":"Optional BCP-47 / provider language hint (for example `en` or `ko`). Omit for auto-detect."},"duration_seconds":{"type":"integer","minimum":1,"maximum":600,"description":"Optional, the audio's length (1–600). It does not set the price: Sume reads the audio's length from the file and bills every started minute."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeRmbgRemoveRequest":{"type":"object","additionalProperties":false,"required":["image_url"],"description":"Sume RMBG 1.0 background-removal request. Provide a public HTTPS image_url. Provider model ids are selected by Sume and are not accepted in this schema.","properties":{"image_url":{"type":"string","format":"uri","description":"Public HTTPS image URL to remove the background from. Prefer a Sume media / attachment URL."},"sync_mode":{"type":"boolean","description":"Optional provider sync_mode passthrough. When omitted, the provider default applies."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeTtsGenerateRequest":{"type":"object","additionalProperties":false,"required":[],"description":"Exactly one of transcript_source or transcript is required. Live-commerce Format generation requires transcript_source and rejects literal transcript even when exact. Generic chat TTS retains literal transcript compatibility. Sume TTS 1.0 text-to-speech request. Provide transcript plus a voice selector: the top-level avatar_id / avatar_handle, or voice.id. avatar_id and avatar_handle are request fields, not properties of voice. The discoverable selector is the avatar reference — list GET /v1/avatar-1.0/avatars and use any avatar whose voice.status is ready — so a caller holding only this contract never needs a voice id it cannot obtain. When an avatar is provided, Sume resolves that avatar's TTS voice at submit time. If both avatar and voice.id are set they must match; otherwise the request fails with 400. TTS 1.0 has no engine picker — model / model_id are rejected with 400; use POST /v1/tts-router/generate to pick an explicit catalog model. output_format defaults to mp3 44100Hz/128kbps (pass wav/pcm_s16le/44100 explicitly when feeding avatar mux). Optional timestamps.words and segmentation.mode=sentence return word timings and gapless per-sentence audio slices. Synthesized audio longer than 1200s fails with tts_duration_exceeded (no credit capture). Authenticate with your Sume API key only — do not send provider credentials.","properties":{"transcript_source":{"type":"object","additionalProperties":false,"required":["script_revision_id","sentence_ids"],"description":"Reference accepted server-owned script text. Obtain IDs from GET /v1/tts-1.0/source in the same authenticated session; the API resolves text before preview, usage reservation, or dispatch. IDs must be unique, contiguous, and in source order. No client text, paths, hashes, or receipts are accepted.","properties":{"script_revision_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"sentence_ids":{"type":"array","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}}},"transcript":{"type":"string","minLength":1,"maxLength":20000,"description":"Text to synthesize. Spaces and punctuation count toward usage. Maximum 20000 characters."},"avatar_id":{"type":"string","minLength":1,"description":"Workspace avatar id, from GET /v1/avatar-1.0/avatars. When set, Sume loads the avatar in the caller workspace and uses its TTS voice id — the avatar's voice.status is ready exactly when this selector works. Talking-head / lip-sync Stage P is unchanged — this only selects a voice for sume/tts-1.0."},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Workspace avatar handle (same grammar as Avatar APIs / Image 1.0), from GET /v1/avatar-1.0/avatars. When both avatar_id and avatar_handle are set they must resolve to the same avatar."},"voice":{"type":"object","additionalProperties":false,"description":"Voice selector (mode=id) for a caller that already holds a Sume TTS voice id. Omit it and select the voice with the top-level avatar_id / avatar_handle instead, which is the route a caller can discover from this contract. When provided together with an avatar reference, voice.id must equal the avatar's resolved TTS voice id.","properties":{"mode":{"type":"string","enum":["id"],"default":"id","description":"Voice selection mode. Only id is supported."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Voice id to synthesize with. Must be a TTS voice UUID (8-4-4-4-12 hex) or a Voices library id (voi_ + 32 hex), not a voice name from another TTS ecosystem — values of any other shape are rejected synchronously with 400 public_reason=invalid_voice_id before a job is queued or credits are reserved. Copy the id verbatim, or send avatar_id / avatar_handle instead and let Sume resolve the voice. Library ids are resolved to the stored TTS voice before the job is queued."}}},"confirm_language_mismatch":{"type":"boolean","description":"Set true only after the user confirms the voice-language mismatch warning. Omit on the initial request. Confirmation does not change the requested voice or language."},"language":{"type":"string","minLength":2,"maxLength":16,"description":"Language the voice speaks the transcript in (BCP-47 / ISO-639, e.g. ko, ja, en). Set it for every non-English transcript — omitted defaults to English at the provider (Sume infers ko/ja from a Hangul/kana-only transcript as a fallback). Never translate a non-English request into English."},"output_format":{"type":"object","additionalProperties":false,"description":"Audio output format. Defaults to mp3 with sample_rate 44100 and bit_rate 128000.","properties":{"container":{"type":"string","enum":["mp3","wav","raw"],"description":"Audio container."},"sample_rate":{"type":"integer","enum":[8000,16000,22050,24000,44100,48000],"description":"Sample rate in Hz."},"bit_rate":{"type":"integer","enum":[32000,64000,96000,128000,192000],"description":"MP3 bit rate. Required for mp3 when overriding defaults."},"encoding":{"type":"string","enum":["pcm_f32le","pcm_s16le","pcm_mulaw","pcm_alaw"],"description":"PCM encoding for wav/raw containers."}}},"pronunciation_dict_id":{"type":"string","minLength":1,"maxLength":128,"description":"Optional pronunciation dictionary id."},"generation_config":{"type":"object","additionalProperties":false,"description":"Optional volume, speed, and emotion controls.","properties":{"volume":{"type":"number","minimum":0.5,"maximum":2,"description":"Volume multiplier in [0.5, 2.0]."},"speed":{"type":"number","minimum":0.6,"maximum":1.5,"description":"Speed multiplier in [0.6, 1.5]."},"emotion":{"type":"string","minLength":1,"maxLength":64,"description":"Optional emotion guide for generation."}}},"speed":{"type":"string","enum":["slow","normal","fast"],"description":"Deprecated speed enum. Prefer generation_config.speed when available."},"timestamps":{"type":"object","additionalProperties":false,"description":"Optional word-level timing request. When words is true, the completed job result includes monotonic words[] with start/end seconds.","properties":{"words":{"type":"boolean","description":"When true, return word-level timings as words[] on the completed job result."}}},"segmentation":{"type":"object","additionalProperties":false,"description":"Optional sentence segmentation. Requires timestamps.words: true. Returns gapless segments[] (segment[i].end == segment[i+1].start) with the +70ms post-word boundary rule by default. emit_audio slices require wav/raw containers.","properties":{"mode":{"type":"string","enum":["sentence"],"description":"Segmentation mode. Only \"sentence\" is supported in v1."},"boundary_lead_ms":{"type":"integer","minimum":0,"maximum":500,"default":70,"description":"Milliseconds after the last word of a sentence before the cut. The next segment absorbs the pause. Default 70."},"emit_audio":{"type":"boolean","default":true,"description":"When true and output_format.container is wav/raw, each segment includes a sample-exact audio_url. For mp3, timings are returned without segment audio_url."}},"required":["mode"]},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"oneOf":[{"required":["transcript"]},{"required":["transcript_source"]}],"anyOf":[{"required":["voice"]},{"required":["avatar_id"]},{"required":["avatar_handle"]}]},"SumeTtsRouterGenerateRequest":{"type":"object","additionalProperties":false,"required":["model"],"description":"Sume TTS Router text-to-speech request. Same transcript, voice-selector, and output rules as TTS 1.0 — the difference is the required `model`: an explicit catalog id from GET /v1/tts-router/models. job.model echoes the requested routable id. Unknown model ids fail with 400 model_not_found and the catalog URL. sonic-* rows keep every TTS 1.0 field. eleven-* rows (ElevenLabs) take transcript, a voice.id from GET /v1/tts-router/voices?family=eleven, language, the output_format values the model lists, and the voice_settings / apply_text_normalization / seed fields the model lists in capabilities.settings; avatar selectors, transcript_source, generation_config, timestamps and segmentation are refused. seed-audio-1.0, qwen-audio-3.0-tts, minimax-speech-2.8-hd and seed-speech take transcript, a preset voice.id from GET /v1/tts-router/voices?family=<the model's voice_family>, language when the model lists languages, the output_format values the model lists, the generation_config keys (speed, volume, pitch, emotion) the model lists in capabilities.settings, and apply_text_normalization on minimax-speech-2.8-hd; avatar selectors, transcript_source, voice_settings, seed, timestamps and segmentation are refused. A transcript longer than the model's capabilities.max_characters fails with 400. Authenticate with your Sume API key only — do not send provider credentials.","properties":{"model":{"type":"string","enum":["sonic-3.6","sonic-3.5","sonic-3","sonic-latest","sonic-preview","sonic-2","sonic-turbo","eleven-v4","eleven-v4-turbo","eleven-v3","eleven-multilingual-v2","eleven-turbo-v2.5","seed-audio-1.0","qwen-audio-3.0-tts","minimax-speech-2.8-hd","seed-speech"],"description":"Required TTS Router catalog model id (pass-through). Not accepted on TTS 1.0."},"transcript_source":{"type":"object","additionalProperties":false,"required":["script_revision_id","sentence_ids"],"description":"Reference accepted server-owned script text. Obtain IDs from GET /v1/tts-1.0/source in the same authenticated session; the API resolves text before preview, usage reservation, or dispatch. IDs must be unique, contiguous, and in source order. No client text, paths, hashes, or receipts are accepted.","properties":{"script_revision_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"sentence_ids":{"type":"array","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}}},"transcript":{"type":"string","minLength":1,"maxLength":20000,"description":"Text to synthesize. Spaces and punctuation count toward usage. Maximum 20000 characters."},"avatar_id":{"type":"string","minLength":1,"description":"Workspace avatar id, from GET /v1/avatar-1.0/avatars. When set, Sume loads the avatar in the caller workspace and uses its TTS voice id — the avatar's voice.status is ready exactly when this selector works. Talking-head / lip-sync Stage P is unchanged — this only selects a voice for sume/tts-1.0."},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Workspace avatar handle (same grammar as Avatar APIs / Image 1.0), from GET /v1/avatar-1.0/avatars. When both avatar_id and avatar_handle are set they must resolve to the same avatar."},"voice":{"type":"object","additionalProperties":false,"description":"Voice selector (mode=id) for a caller that already holds a Sume TTS voice id. Omit it and select the voice with the top-level avatar_id / avatar_handle instead, which is the route a caller can discover from this contract. When provided together with an avatar reference, voice.id must equal the avatar's resolved TTS voice id.","properties":{"mode":{"type":"string","enum":["id"],"default":"id","description":"Voice selection mode. Only id is supported."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Voice id to synthesize with. Must be a TTS voice UUID (8-4-4-4-12 hex) or a Voices library id (voi_ + 32 hex), not a voice name from another TTS ecosystem — values of any other shape are rejected synchronously with 400 public_reason=invalid_voice_id before a job is queued or credits are reserved. Copy the id verbatim, or send avatar_id / avatar_handle instead and let Sume resolve the voice. Library ids are resolved to the stored TTS voice before the job is queued."}}},"confirm_language_mismatch":{"type":"boolean","description":"Set true only after the user confirms the voice-language mismatch warning. Omit on the initial request. Confirmation does not change the requested voice or language."},"language":{"type":"string","minLength":2,"maxLength":16,"description":"Language the voice speaks the transcript in (BCP-47 / ISO-639, e.g. ko, ja, en). Set it for every non-English transcript — omitted defaults to English at the provider (Sume infers ko/ja from a Hangul/kana-only transcript as a fallback). Never translate a non-English request into English."},"output_format":{"type":"object","additionalProperties":false,"description":"Audio output format, one of the model's capabilities.output_formats. Defaults to mp3 with sample_rate 44100 and bit_rate 128000; preset rows default to their first listed format.","properties":{"container":{"type":"string","enum":["mp3","wav","raw"],"description":"Audio container."},"sample_rate":{"type":"integer","enum":[8000,16000,22050,24000,32000,44100,48000],"description":"Sample rate in Hz. 32000 is only for rows that list it (minimax-speech-2.8-hd)."},"bit_rate":{"type":"integer","enum":[32000,64000,96000,128000,192000],"description":"MP3 bit rate. Required for mp3 when overriding defaults."},"encoding":{"type":"string","enum":["pcm_f32le","pcm_s16le","pcm_mulaw","pcm_alaw"],"description":"PCM encoding for wav/raw containers."}}},"pronunciation_dict_id":{"type":"string","minLength":1,"maxLength":128,"description":"Optional pronunciation dictionary id."},"generation_config":{"type":"object","additionalProperties":false,"description":"sonic-* and preset rows: the keys the model lists in capabilities.settings, inside that setting's min / max.","properties":{"volume":{"type":"number","minimum":0.5,"maximum":2,"description":"Volume multiplier in [0.5, 2.0]."},"speed":{"type":"number","minimum":0.5,"maximum":2,"description":"Speed multiplier. sonic-* rows take [0.6, 1.5]; preset rows take [0.5, 2.0]."},"pitch":{"type":"integer","minimum":-12,"maximum":12,"description":"Preset rows that list pitch: semitones up or down."},"emotion":{"type":"string","minLength":1,"maxLength":64,"description":"One of the model's capabilities.settings.emotions."}}},"speed":{"type":"string","enum":["slow","normal","fast"],"description":"Deprecated speed enum. Prefer generation_config.speed when available."},"timestamps":{"type":"object","additionalProperties":false,"description":"Optional word-level timing request. When words is true, the completed job result includes monotonic words[] with start/end seconds.","properties":{"words":{"type":"boolean","description":"When true, return word-level timings as words[] on the completed job result."}}},"segmentation":{"type":"object","additionalProperties":false,"description":"Optional sentence segmentation. Requires timestamps.words: true. Returns gapless segments[] (segment[i].end == segment[i+1].start) with the +70ms post-word boundary rule by default. emit_audio slices require wav/raw containers.","properties":{"mode":{"type":"string","enum":["sentence"],"description":"Segmentation mode. Only \"sentence\" is supported in v1."},"boundary_lead_ms":{"type":"integer","minimum":0,"maximum":500,"default":70,"description":"Milliseconds after the last word of a sentence before the cut. The next segment absorbs the pause. Default 70."},"emit_audio":{"type":"boolean","default":true,"description":"When true and output_format.container is wav/raw, each segment includes a sample-exact audio_url. For mp3, timings are returned without segment audio_url."}},"required":["mode"]},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."},"voice_settings":{"type":"object","additionalProperties":false,"description":"ElevenLabs rows only, and only the keys the model lists in its catalog settings.","properties":{"stability":{"type":"number","minimum":0,"maximum":1,"description":"Lower is more expressive (creative), higher more consistent (robust). Default 0.5."},"similarity_boost":{"type":"number","minimum":0,"maximum":1,"description":"How closely to match the voice. Default 0.75."},"style":{"type":"number","minimum":0,"maximum":1,"description":"Style exaggeration. Default 0."},"speed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"Speaking rate. Default 1."}}},"apply_text_normalization":{"type":"string","enum":["auto","on","off"],"description":"ElevenLabs rows and minimax-speech-2.8-hd: whether numbers and abbreviations are spelled out. Default auto (MiniMax reads auto as off)."},"seed":{"type":"integer","minimum":0,"maximum":4294967295,"description":"ElevenLabs v4 rows only: best-effort reproducibility; identical audio is not guaranteed."}},"oneOf":[{"required":["transcript"]},{"required":["transcript_source"]}],"anyOf":[{"required":["voice"]},{"required":["avatar_id"]},{"required":["avatar_handle"]}]},"TtsRouterCatalogItem":{"type":"object","additionalProperties":false,"required":["id","name","modality","routing","capabilities","pricing","constraints"],"properties":{"id":{"type":"string","enum":["sonic-3.6","sonic-3.5","sonic-3","sonic-latest","sonic-preview","sonic-2","sonic-turbo","eleven-v4","eleven-v4-turbo","eleven-v3","eleven-multilingual-v2","eleven-turbo-v2.5","seed-audio-1.0","qwen-audio-3.0-tts","minimax-speech-2.8-hd","seed-speech"]},"name":{"type":"string"},"voice_family":{"type":"string","enum":["sonic","eleven","seed_audio","qwen","minimax","seed_speech"],"description":"Which GET /v1/tts-router/voices?family= list this model speaks with."},"modality":{"type":"string","enum":["audio"]},"routing":{"type":"string","enum":["pass_through"]},"capabilities":{"type":"object","additionalProperties":false,"required":["text_to_speech","max_characters"],"properties":{"text_to_speech":{"type":"boolean"},"max_characters":{"type":"integer"},"languages":{"type":"array","items":{"type":"string"},"description":"ISO 639-1 codes the provider documents for the model."},"output_formats":{"type":"array","items":{"type":"string"},"description":"Output formats as container_sampleRate[_kbps], e.g. mp3_44100_128."},"settings":{"type":"object","additionalProperties":true,"description":"Settings the model takes, each with min / max / step / default: stability, similarityBoost, style, speed (speedField says voice_settings or generation_config), volume, pitch, emotions, seed, textNormalization. An absent key is a setting the model refuses."}}},"pricing":{"type":"object","additionalProperties":false,"description":"Credits per 1,000 transcript characters on this model (two decimals, rounded up). A request is charged its whole total once, rounded up.","required":["basis","credits_per_1000_characters"],"properties":{"basis":{"type":"string","enum":["per_character"]},"credits_per_1000_characters":{"type":"number","minimum":0}}},"constraints":{"type":"array","items":{"type":"string"}}}},"TtsRouterModelsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/TtsRouterCatalogItem"}}}}}},"TtsRouterModelResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"$ref":"#/components/schemas/TtsRouterCatalogItem"}}}}},"TtsRouterVoice":{"type":"object","additionalProperties":false,"required":["id","family","name","description","language","gender","accent","country","preview_url","tags"],"properties":{"id":{"type":"string"},"family":{"type":"string","enum":["sonic","eleven","seed_audio","qwen","minimax","seed_speech"]},"name":{"type":"string"},"description":{"type":["null","string"]},"language":{"type":["null","string"]},"gender":{"type":["null","string"],"enum":["male","female","neutral",null]},"accent":{"type":["null","string"]},"country":{"type":["null","string"],"pattern":"^[A-Z]{2}$"},"preview_url":{"type":["null","string"]},"tags":{"type":"array","items":{"type":"string"}}}},"TtsRouterVoicesResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["family","source","voices"],"properties":{"family":{"type":"string","enum":["sonic","eleven","seed_audio","qwen","minimax","seed_speech"]},"source":{"type":"string","enum":["live","premade","preset"],"description":"live: read from the voice library (cached ten minutes). premade: the ElevenLabs premade voices, served when no ElevenLabs account is connected. preset: the fixed voice list the provider offers for seed_audio, qwen, minimax and seed_speech models."},"voices":{"type":"array","items":{"$ref":"#/components/schemas/TtsRouterVoice"}}}}}},"SumeMusicRouterGenerateRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"description":"Sume Music Router text-to-music request. Same prompt / image_url rules as Music 1.0 plus an optional routable `model` from GET /v1/music-router/models; omitted means `sume/music-auto`, which resolves to Lyria 3.5 today. job.model echoes the requested routable id. Unknown model ids fail with 400 model_not_found and the catalog URL.","properties":{"model":{"type":"string","enum":["sume/music-auto","lyria-3.5","lyria-3-pro","elevenlabs-music-2.5","minimax-music-2.6","lyria-2","stable-audio-2.5","ace-step"],"description":"Optional Music Router catalog model id. Default `sume/music-auto` (Sume picks the engine). Not accepted on Music 1.0."},"prompt":{"type":"string","minLength":1,"maxLength":5000,"description":"Text prompt for Sume Music 1.0. Write a per-scene music brief: emotion, genre, a BPM number, key/mode, lead instruments with texture, one named arc moment, era/production, then \"Instrumental, no vocals.\" Provider model ids are selected by Sume and are not accepted in this schema. Do not include duration or duration_seconds."},"negative_prompt":{"type":"string","default":"","description":"Not supported by Music 1.0 / Lyria 3. Omit the field or send an empty string. Non-empty values are rejected with public_reason=negative_prompt_unsupported. Put exclusions (no vocals, no spoken word, etc.) into the positive prompt instead."},"image_url":{"type":"string","format":"uri","nullable":true,"description":"Optional public HTTPS image URL used as a visual conditioning input; use the accepted scene still when appropriate. Null clears the image input."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."},"duration_seconds":{"type":"integer","minimum":1,"maximum":600,"description":"The track's length in whole seconds, on the models whose catalog row lists capabilities.duration_seconds (within that range; the row's default when omitted). Refused on the others, which set their length from the prompt."}}},"MusicRouterCatalogItem":{"type":"object","additionalProperties":false,"required":["id","name","modality","routing","capabilities","pricing","constraints"],"properties":{"id":{"type":"string","enum":["sume/music-auto","lyria-3.5","lyria-3-pro","elevenlabs-music-2.5","minimax-music-2.6","lyria-2","stable-audio-2.5","ace-step"]},"name":{"type":"string"},"modality":{"type":"string","enum":["audio"]},"routing":{"type":"string","enum":["auto","pass_through"]},"resolves_to":{"type":"string","enum":["sume/music-auto","lyria-3.5","lyria-3-pro","elevenlabs-music-2.5","minimax-music-2.6","lyria-2","stable-audio-2.5","ace-step"],"description":"Catalog id an `auto` row resolves to today."},"capabilities":{"type":"object","additionalProperties":false,"required":["text_to_music","image_conditioning","lyrics","max_prompt_characters"],"properties":{"text_to_music":{"type":"boolean"},"image_conditioning":{"type":"boolean"},"lyrics":{"type":"boolean"},"max_prompt_characters":{"type":"integer"},"duration_seconds":{"type":"object","additionalProperties":false,"required":["min","max","default"],"description":"The lengths duration_seconds takes; absent where the model sets its own length.","properties":{"min":{"type":"integer"},"max":{"type":"integer"},"default":{"type":"integer"}}}}},"pricing":{"type":"object","additionalProperties":false,"description":"Credits one generation is charged on this model (at its default length where it is priced by length).","required":["basis","credits_per_audio"],"properties":{"basis":{"type":"string","enum":["per_audio","per_second","per_minute"]},"credits_per_audio":{"type":"integer","minimum":0},"credits_per_minute":{"type":"integer","minimum":0,"description":"Rows priced by length: credits per minute of track."}}},"constraints":{"type":"array","items":{"type":"string"}}}},"MusicRouterModelsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/MusicRouterCatalogItem"}}}}}},"MusicRouterModelResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"$ref":"#/components/schemas/MusicRouterCatalogItem"}}}}},"SumeVideoUpscaleRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"description":"Sume Video Upscale 1.0 request. Provide a public HTTPS video_url. Provider model ids are selected by Sume and are not accepted in this schema.","properties":{"video_url":{"type":"string","format":"uri","description":"Public HTTPS video URL to upscale."},"upscale_factor":{"type":"number","minimum":1.1,"maximum":4,"description":"Alias of scale_ratio. Accepted only with resolution, which replaces it."},"scale_ratio":{"type":"number","minimum":1.1,"maximum":4,"description":"Accepted only with resolution, which replaces it. Send resolution instead."},"duration_seconds":{"type":"number","minimum":1,"maximum":30,"description":"Optional, the clip's length in seconds. It does not set the price: Sume reads the clip's length from the file and bills every second of it, rounded up, at most 600 (an unreadable clip is billed 600 s)."},"enhancement_tier":{"type":"string","enum":["fast","standard","pro"],"description":"Enhancement tier (default fast). fast and standard bill the resolution's per-second rate; pro bills 10 times that rate."},"resolution":{"type":"string","enum":["1080p","2K","4K"],"description":"Output resolution, priced per second at that tier: 1080p, 2K or 4K. Default 1080p."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeAvatarImageToVideoRequest":{"type":"object","additionalProperties":false,"required":["audio_url","duration_seconds"],"description":"VEED Fabric 1.0 request. Provide exactly one visual source (`image_url` or `avatar_id`/`avatar_handle`) plus a Sume-hosted `audio_url`. Provider queue ids are selected by Sume and are not accepted in this schema.","properties":{"image_url":{"type":"string","format":"uri","description":"Public HTTPS still image URL for audio-driven image-to-video. Mutually exclusive with avatar_id/avatar_handle."},"avatar_id":{"type":"string","minLength":1,"description":"Ready avatar id. Resolved server-side to the avatar identity still. Mutually exclusive with image_url."},"avatar_handle":{"type":"string","minLength":1,"description":"Ready avatar handle. Resolved server-side to the avatar identity still. Mutually exclusive with image_url."},"audio_url":{"type":"string","format":"uri","description":"Public HTTPS audio URL on the Sume media host (typically a TTS segment). Non-Sume hosts are rejected. Max 10 MB."},"duration_seconds":{"type":"number","minimum":1,"maximum":300,"description":"The audio's length in seconds, 1–300. It does not set the price: Sume reads the audio's length from the file (WAV, MP3, M4A, FLAC, Ogg) and bills every second of it, rounded up, at most 300, at the resolution's per-second rate (an unreadable file is billed 300 s)."},"resolution":{"type":"string","enum":["480p","720p"],"description":"Output resolution (default 720p)."},"speed_tier":{"type":"string","enum":["standard","fast"],"description":"Accepted for body compatibility and ignored: Fabric 1.0 has one speed tier and never runs on a fast tier."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeAvatarFabricRequest":{"type":"object","additionalProperties":false,"required":["audio_url","duration_seconds"],"description":"EXPERIMENTAL Sume Avatar 1.0 Fabric request. Accepts the same body as VEED Fabric 1.0 so the two can be compared on identical inputs, except that `duration_seconds` is capped at 15 and `speed_tier` is ignored. This is a test-only surface and the model id `sume/avatar-1.0/fabric` will change before general availability.","properties":{"image_url":{"type":"string","format":"uri","description":"Public HTTPS still image URL for audio-driven image-to-video. Mutually exclusive with avatar_id/avatar_handle."},"avatar_id":{"type":"string","minLength":1,"description":"Ready avatar id. Resolved server-side to the avatar identity still. Mutually exclusive with image_url."},"avatar_handle":{"type":"string","minLength":1,"description":"Ready avatar handle. Resolved server-side to the avatar identity still. Mutually exclusive with image_url."},"audio_url":{"type":"string","format":"uri","description":"Public HTTPS audio URL on the Sume media host (typically a TTS segment). Non-Sume hosts are rejected. Max 10 MB."},"duration_seconds":{"type":"number","minimum":1,"maximum":15,"description":"Audio duration seconds. Rounded up and clamped into the 4-15 second window the experimental backend supports, then used to reserve credits at admit. Requests above 15 are rejected rather than truncated."},"resolution":{"type":"string","enum":["480p","720p"],"description":"Output resolution (default 720p)."},"speed_tier":{"type":"string","enum":["standard","fast"],"description":"Accepted for body compatibility with VEED Fabric 1.0 and ignored: the experimental backend has a single fixed speed tier."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeKlingMotionControlRequest":{"type":"object","additionalProperties":false,"required":["motion_video_url","duration_seconds"],"description":"Kling 3.0 Motion Control request. Provide exactly one visual source (`image_url` or `avatar_id`/`avatar_handle`) plus a public HTTPS motion reference video. The still is animated with the driving video's motion; output length follows the driving video. Provider queue ids are selected by Sume and are not accepted in this schema.","properties":{"image_url":{"type":"string","format":"uri","description":"Public HTTPS still image URL to animate with the driving motion video. Mutually exclusive with avatar_id/avatar_handle."},"avatar_id":{"type":"string","minLength":1,"description":"Ready avatar id. Resolved server-side to the avatar identity still. Mutually exclusive with image_url."},"avatar_handle":{"type":"string","minLength":1,"description":"Ready avatar handle. Resolved server-side to the avatar identity still. Mutually exclusive with image_url."},"motion_video_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS motion reference video URL that drives the output motion. Maximum 30 seconds."},"prompt":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional guidance prompt. Motion and framing follow the driving video; the prompt only steers appearance details."},"duration_seconds":{"type":"number","minimum":1,"maximum":30,"description":"Motion video duration seconds used to reserve credits at admit (ceil × the per-second rate). Output length follows the driving video. Max 30."},"keep_original_sound":{"type":"boolean","description":"Keep the driving video's audio track in the output (default true). Set false for a silent clip."},"character_orientation":{"type":"string","enum":["video","image"],"description":"Whose framing wins: `video` (default) keeps the driving video's orientation, `image` keeps the still's orientation."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeTimelineRequest":{"type":"object","additionalProperties":false,"required":["audio","video"],"description":"Sume Timeline 1.0 declarative long-form render request. One continuous audio spine plus ordered video slots with optional transitions. Declared starts are authoritative — Sume compensates xfade internally. No filtergraph, ffmpeg args, codec, or shell fields are accepted. All media URLs must already be Sume-hosted.","properties":{"output":{"type":"object","additionalProperties":false,"description":"Output frame geometry and rate.","properties":{"width":{"type":"integer","minimum":256,"maximum":2160,"description":"Even width in pixels (default 1080)."},"height":{"type":"integer","minimum":256,"maximum":2160,"description":"Even height in pixels (default 1920)."},"fps":{"type":"integer","enum":[24,25,30,60],"description":"Output frames per second. Omit it to render at the rate the sources already run at (the longest video sources decide; stills have no rate; 30 only when nothing has one). A rate that differs from a source's is met by repeating or dropping a frame every few frames — visible judder on camera moves and gestures — and is reported as output_fps_resamples_sources with the rate the sources wanted."},"format":{"type":"string","enum":["mp4"],"description":"Output container (mp4 only in v1)."},"fade_in_seconds":{"type":"number","minimum":0,"maximum":5,"description":"Fade the first seconds up from black and silence. Snapped to whole frames; fade_in_seconds + fade_out_seconds must fit inside the spine."},"fade_out_seconds":{"type":"number","minimum":0,"maximum":5,"description":"Fade the last seconds down to black and silence. Snapped to whole frames."}}},"audio":{"type":"object","additionalProperties":false,"required":["duration_seconds"],"description":"Output audio. Default: a single continuous voiceover spine (url + duration_seconds). Pass parts[] instead of url to join ordered slices — per-sentence TTS output, for example — into one gapless spine at render time. Set mode \"silence\" to render without a spine — a silent montage, a BGM-only slideshow (the soundtrack is no longer forced to be the spine), or an end card that outlives the voiceover. Output duration always equals duration_seconds.","properties":{"mode":{"type":"string","enum":["silence"],"description":"Omit for a voiceover spine. \"silence\" renders a silent audio track of duration_seconds and takes no url, gain_db or parts; add a soundtrack for BGM-only."},"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS audio URL. Required unless mode is silence or parts is set. The master inherits this file's sample rate and channel count, so pass a spine-grade file: audio_detach wav output (source rate and channels), a TTS master, or an uploaded master. video_inspect transcript.audio_url is a 16 kHz mono speech-to-text rendition and renders as one — a spine under 32 kHz, or mono under stereo video sources, is reported as audio_spine_low_fidelity."},"parts":{"type":"array","minItems":1,"maxItems":20,"description":"Ordered spine slices joined gaplessly, as an alternative to a single url (audio_url_and_parts_exclusive if both are sent). The join happens in the sample domain — no re-synthesis, no silence inserted at the seams — so two short voiceover lines become one continuous spine without re-running TTS. Each part may carry its own source_in / duration, so a split and a combine are expressible in one document. All URLs must be Sume-hosted. audio.source_in is rejected here (audio_source_in_requires_single_spine); cut per part instead. The parts must together hold at least duration_seconds, otherwise the request fails audio_parts_shorter_than_duration. To reuse one merged file across renders — or to feed it to Avatar 1.0 image-to-video — mint a durable URL with POST /v1/timeline-1.0/audio instead.","items":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS audio URL for this slice."},"source_in":{"type":"number","minimum":0,"description":"In-point into this slice in seconds (default 0)."},"duration":{"type":"number","exclusiveMinimum":0,"description":"Length taken from this slice in seconds. Omit to use the rest of the file from source_in."}}}},"duration_seconds":{"type":"number","minimum":1,"maximum":1800,"description":"Declared audio duration used for credit reserve and output -t. Max 1800."},"gain_db":{"type":"number","minimum":-60,"maximum":12,"description":"Optional gain applied to the spine (default 0)."},"source_in":{"type":"number","minimum":0,"description":"In-point into the spine file in seconds (default 0), mirroring video[].source_in. The spine plays from here and the output still runs duration_seconds, so a finished show can be re-cut — drop the opening, keep one section — without re-synthesizing the voice. Re-base video[].start to the new origin or the picture drifts against the voice. The file must hold source_in + duration_seconds; otherwise the render fails audio_source_in_exceeds_source. Rejected with mode silence (silent_audio_takes_no_source_in)."}}},"soundtrack":{"type":"object","additionalProperties":false,"required":["url"],"description":"Optional background music mixed under the spine, or the whole audio track when audio.mode is silence.","properties":{"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS soundtrack URL."},"gain_db":{"type":"number","minimum":-60,"maximum":12,"description":"Soundtrack gain in dB (default -16 — a bed level under a spine). With audio.mode silence the bed is the whole track, so set 0 unless you want it quiet."},"loop":{"type":"boolean","description":"Repeat the bed until the spine ends. Without it a soundtrack shorter than audio.duration_seconds stops partway through and the render warns soundtrack_shorter_than_spine."},"fade_out_seconds":{"type":"number","minimum":0,"maximum":10,"description":"Fade the bed out over the last seconds of the spine (default 0 — the bed stops dead)."},"duck_db":{"type":"number","minimum":0,"maximum":20,"description":"Target attenuation of the bed while the spine is speaking, as a fixed-shape sidechain duck (default 0 — a static bed at gain_db). A duck follows the spine envelope, so this is a target depth against a spine at speech level rather than a constant gain. Rejected with audio.mode silence (duck_requires_audio_spine) — there is no spine to key off."}}},"video":{"type":"array","minItems":1,"maxItems":200,"description":"Ordered video slots. segment.transition describes the boundary into that segment; video[0].transition is rejected.","items":{"type":"object","additionalProperties":false,"required":["source_url","start","duration"],"properties":{"source_url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS video URL for this slot."},"start":{"type":"number","minimum":0,"description":"Authoritative on-screen start in seconds on the audio spine."},"duration":{"type":"number","minimum":0.2,"description":"On-screen duration in seconds (excluding transition into next)."},"source_in":{"type":"number","minimum":0,"description":"In-point into the source media (default 0)."},"fit":{"type":"string","enum":["cover","contain","stretch","blur"],"description":"Scale/crop mode (default cover). Mapped to fixed filter chains. blur pads a mismatched aspect ratio with a blurred copy of the frame instead of black bars."},"motion":{"type":"object","additionalProperties":false,"required":["type"],"deprecated":true,"description":"Deprecated and ignored. Timeline combines and splits media; a still is rendered as a static hold. Sending it is accepted and answered with a motion_ignored warning.","properties":{"type":{"type":"string"}}},"transition":{"type":"object","additionalProperties":false,"required":["type","duration"],"description":"Transition into this segment. type is an enum mapped to a fixed xfade literal.","properties":{"type":{"type":"string","enum":["fade","wipeleft","wiperight","slideup","slidedown","dissolve"]},"duration":{"type":"number","minimum":0.001,"maximum":1,"description":"Transition duration ≤1.0s and ≤50% of the shorter neighbouring segment."}}}}}},"render":{"type":"object","additionalProperties":false,"description":"Optional assemble controls. Defaults keep long timelines working with no client change: auto chunks past chunk_max_segments segments and auto pad_mode loops short sources instead of holding a long freeze.","properties":{"strategy":{"type":"string","enum":["auto","single","chunked"],"description":"Assemble strategy (default auto). single keeps the whole timeline in one ffmpeg graph and is only accepted up to 12 segments (render_strategy_unsafe)."},"chunk_max_segments":{"type":"integer","minimum":4,"maximum":32,"description":"Segments per chunk when chunking (default 12)."},"pad_mode":{"type":"string","enum":["auto","loop","freeze"],"description":"How a slot longer than its source is filled (default auto): loop replays the source, freeze holds the last frame."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request (e.g. production_id)."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeTimelineAudioRequest":{"type":"object","additionalProperties":false,"required":["operation"],"description":"Sume Timeline 1.0 audio request. Joins Sume-hosted audio into one gapless file (operation concat) or slices one file into ranges (operation split), and returns the results as durable media.sume.com URLs. Sample-domain work only: no re-synthesis, no provider inference, and no filtergraph, ffmpeg args, codec or shell fields. Use audio.parts[] on POST /v1/timeline-1.0/render instead when the joined spine is only needed for that one render.","properties":{"operation":{"type":"string","enum":["concat","split"],"description":"concat joins parts[] in order into one file. split cuts url into ranges[], one file per range."},"parts":{"type":"array","minItems":1,"maxItems":20,"description":"Ordered slices to join, for operation concat. Each may carry its own source_in / duration, so a document can cut and join in one call. All URLs must be Sume-hosted, and they must share one channel layout (audio_parts_channel_mismatch otherwise).","items":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS audio URL for this slice."},"source_in":{"type":"number","minimum":0,"description":"In-point into this slice in seconds (default 0)."},"duration":{"type":"number","exclusiveMinimum":0,"description":"Length taken from this slice. Omit to use the rest of the file from source_in."}}}},"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS audio URL to slice, for operation split. Rejected with operation concat."},"ranges":{"type":"array","minItems":1,"maxItems":20,"description":"Time ranges to cut out of url, for operation split. One output file per range, in this order. Ranges may overlap.","items":{"type":"object","additionalProperties":false,"required":["start"],"properties":{"start":{"type":"number","minimum":0,"description":"Range start in seconds from the start of the file."},"end":{"type":"number","exclusiveMinimum":0,"description":"Range end in seconds. Omit to slice to the end of the file."}}}},"output":{"type":"object","additionalProperties":false,"description":"Output container. Defaults to wav.","properties":{"format":{"type":"string","enum":["wav","mp3"],"description":"wav (pcm_s16le, default) stays sample-exact, so the result can be joined again or used to drive Avatar 1.0 image-to-video without picking up encoder delay. mp3 is smaller but re-introduces priming padding at every edge."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeTimelineComposeRequest":{"type":"object","additionalProperties":false,"required":["operation","image","video"],"description":"Sume Timeline 1.0 compose request. Puts one Sume-hosted still and one Sume-hosted video on screen at the same time and returns one durable media.sume.com MP4. mode stack splits the frame and tiles the layers into it (반배너 / half-banner: horizontal split, banner image on top, avatar video underneath); operation overlay floats the still over a full-frame video. Output length always comes from the video layer — the still is held for the clip and can never set the duration. The composed MP4 is an ordinary video[] slot for POST /v1/timeline-1.0/render. Sequential image-then-video is not expressible here on purpose: adjacent render slots already do it. No filtergraph, ffmpeg args, codec or shell fields.","properties":{"operation":{"type":"string","enum":["stack","overlay"],"description":"stack tiles the still and the video into two regions of one frame. overlay floats the still on top of a full-frame video. Named operation, not mode: mode is the reserved communication option on every Sume launch body."},"image":{"type":"object","additionalProperties":false,"required":["url"],"description":"The held layer. Must be a still image (PNG/JPEG/WebP/…); a video here is rejected as compose_image_not_still.","properties":{"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS still image URL."}}},"video":{"type":"object","additionalProperties":false,"required":["url"],"description":"The moving layer. It carries the time axis and the audio of the composed clip.","properties":{"url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS video URL."},"source_in":{"type":"number","minimum":0,"description":"In-point into the video file in seconds (default 0). The still is always held from the start of the clip."},"duration":{"type":"number","minimum":0.2,"maximum":300,"description":"Clip length in seconds. Omit to use the rest of the file from source_in. A duration past the end of the source is clamped to what the source holds (compose_duration_clamped_to_source)."}}},"layout":{"type":"object","additionalProperties":false,"description":"Geometry. The vocabulary is mode-dependent: split / image_region / ratio / image_fit belong to stack, position / width_ratio / margin_ratio to overlay, and sending the wrong set is a 400 rather than a silent render.","properties":{"split":{"type":"string","enum":["horizontal","vertical"],"description":"stack only. horizontal (default) cuts top/bottom — the 반배너 axis. vertical cuts left/right."},"image_region":{"type":"string","enum":["top","bottom","left","right"],"description":"stack only. Which side the still takes; must match the split axis. Defaults to top on a horizontal split, left on a vertical one."},"ratio":{"type":"number","minimum":0.1,"maximum":0.9,"description":"stack only. The still region's share of the split axis (default 0.5 — the half-banner). The video takes the remainder exactly, so the two regions always tile the frame."},"image_fit":{"type":"string","enum":["cover","contain","stretch"],"description":"stack only. How the still fills its region (default cover)."},"video_fit":{"type":"string","enum":["cover","contain","stretch"],"description":"How the video fills its region (stack) or the frame (overlay). Default cover. On a half-height region cover crops roughly half the source frame, so check that the face survives."},"position":{"type":"string","enum":["top","center","bottom"],"description":"overlay only. Where the plate is pinned (default top). It is always centred horizontally."},"width_ratio":{"type":"number","minimum":0.05,"maximum":1,"description":"overlay only. Plate width as a fraction of the output width (default 0.9). The plate keeps its own aspect ratio."},"margin_ratio":{"type":"number","minimum":0,"maximum":0.45,"description":"overlay only. Inset from the pinned edge as a fraction of the output height (default 0.05). Ignored for position center."}}},"output":{"type":"object","additionalProperties":false,"description":"Output frame. Defaults to 1080x1920; fps omitted renders at the video layer's own rate, which is the only rate that repeats or drops no frame (an explicit rate that differs warns output_fps_resamples_sources). Match width and height to the timeline this clip will be assembled into — a live-commerce lane rendering 720x1280 should compose at 720x1280 so the clip is never rescaled.","properties":{"width":{"type":"integer","minimum":256,"maximum":2160},"height":{"type":"integer","minimum":256,"maximum":2160},"fps":{"type":"integer","enum":[24,25,30,60]}}},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeVideoFilterRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"description":"Sume Video filter 1.0 request. Applies a validated program to one Sume-hosted clip and returns one durable media.sume.com MP4 (artifact artf_…). The program is ops[] (dim, crop) and/or a filters-only filtergraph; at least one is required. The server always injects the input from video_url, writes the output and picks the encoder, so there is no -i, argv, codec, preset, crf or shell field — sending one is 400 ffmpeg_fields_rejected. filtergraph is checked by contract: every filter must be on the hosted allowlist (unknown → 400 invalid_filtergraph), labels may only be internal, and the graph must start and end with a filter. Check it for free first with POST /v1/video-filter/check. Encode may still fail on the box (a bad expression, memory, time) — that is a structured job error, not a crash; fix and resubmit. Geometry, frame rate and audio are inherited unless the program changes them. Max 300 seconds of source. Reserved at 6.4 credits per encode job, captured at the pass's own compute at list price, idle time included, never above the reservation.","properties":{"video_url":{"type":"string","format":"uri","description":"Sume-hosted HTTPS video URL (media.sume.com) already generated in this workspace. The filtered MP4 is a new artifact URL; the source is not modified."},"ops":{"type":"array","maxItems":8,"description":"Ordered program, applied in sequence before filtergraph. dim: {op, amount}; crop: {op, x, y, width, height} as fractions of the source frame. An unknown op is 400 unsupported_filter_op, an extra key on an op is 400 unsupported_filter_op_field.","items":{"type":"object","additionalProperties":false,"required":["op"],"properties":{"op":{"type":"string","enum":["dim","crop"],"description":"dim darkens the whole clip; crop keeps a rectangle of the frame (even-rounded)."},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1,"description":"dim only. Luma multiplier in (0, 1]. 0.45 is a clearly darker picture; 0.8 a subtle one; 1 leaves the clip unchanged. Black stays black and colours do not shift."},"x":{"type":"number","minimum":0,"maximum":1,"description":"crop only. Left edge as a fraction of the source width."},"y":{"type":"number","minimum":0,"maximum":1,"description":"crop only. Top edge as a fraction of the source height."},"width":{"type":"number","minimum":0.05,"maximum":1,"description":"crop only. Kept width as a fraction of the source width; x + width ≤ 1."},"height":{"type":"number","minimum":0.05,"maximum":1,"description":"crop only. Kept height as a fraction of the source height; y + height ≤ 1."}}}},"filtergraph":{"type":"string","minLength":1,"maxLength":2048,"description":"Optional filters-only ffmpeg filtergraph applied after ops[], e.g. \"eq=contrast=1.2:saturation=0.8,gblur=sigma=2\". No inputs, no outputs, no paths: the server wraps it as [0:v]…[vout]. Internal labels (split[a][b];[a]…[b]overlay) are fine; stream specifiers ([0:v]) are not. Only allowlisted pixel filters are accepted (eq, lutyuv, hue, colorbalance, curves-free tone filters, blur/sharpen, crop/scale/pad/flip/transpose/rotate, fps/tpad/fade, split/overlay/hstack/vstack/blend/drawbox, …); movie, subtitles, drawtext, lut3d and anything that reads a file or a socket are not filters here."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeVideoFilterCheckRequest":{"type":"object","additionalProperties":true,"description":"The same body as SumeVideoFilterRequest (video_url + ops[] and/or filtergraph). Every constraint is reported back as a diagnostic instead of a 400, so any JSON object is accepted here."},"VideoFilterCheck":{"type":"object","additionalProperties":false,"required":["object","valid","encode","diagnostics","program","estimate","next_action"],"description":"Unbilled video filter program check. Runs the schema, the program contract (op whitelist, filtergraph allowlist / labels / alphabet) and the source preflight, and returns diagnostics. Never boots a box or touches the encoder; an encode that passes the check can still fail on the box for a bad expression, memory or time.","properties":{"object":{"type":"string","enum":["video_filter_check"]},"valid":{"type":"boolean"},"encode":{"type":"string","enum":["not_run"]},"diagnostics":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["severity","code","message"],"properties":{"severity":{"type":"string","enum":["error"]},"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"next_action":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"program":{"type":["null","object"],"additionalProperties":false,"required":["video_url","ops","filtergraph","filter_count","filters"],"description":"The normalized program when the document parsed, with the compiled filter names (no argv, no paths). null when the document itself was rejected.","properties":{"video_url":{"type":"string"},"ops":{"type":"array","items":{"type":"object","additionalProperties":true}},"filtergraph":{"type":["null","string"]},"filter_count":{"type":"integer"},"filters":{"type":"array","items":{"type":"string"}}}},"estimate":{"type":["null","object"],"additionalProperties":false,"description":"What one encode job is charged: `usd` in US dollars (the figure to quote), `credits` for older clients.","required":["credits","label"],"properties":{"credits":{"type":"integer","minimum":0},"usd":{"type":"string"},"label":{"type":"string"}}},"next_action":{"type":"string","enum":["submit_video_filter","fix_program_and_recheck"]}}},"SumeVideoTrimRequest":{"type":"object","additionalProperties":false,"required":["video_url","start"],"description":"Sume Video trim 1.0 request. Cuts a [start, end) range out of ONE Sume-hosted clip into a NEW durable media.sume.com MP4; the source is untouched. Exactly one of end / duration. precision exact (default) re-encodes frame-accurately and may conform the output once (width / height / fps); keyframe stream-copies from the nearest earlier keyframe and reports the actual in-point. Not placement: sequencing, transitions and the audio spine are POST /v1/timeline-1.0/render. The server compiles the ffmpeg, so there is no -i, argv, codec, preset, crf, filtergraph or shell field — sending one is 400 ffmpeg_fields_rejected. Max 1800 seconds of source and 900 seconds of output; past the source it clamps (trim_clamped_to_source). Reserved at 6.4 credits per job, captured at the pass's own compute at list price, idle time included, never above the reservation.","properties":{"video_url":{"type":"string","format":"uri","description":"media.sume.com video already generated in this workspace. The trimmed MP4 is a new artifact URL; the source is not modified."},"start":{"type":"number","minimum":0,"description":"In-point, seconds from the start of the source."},"end":{"type":"number","exclusiveMinimum":0,"description":"Out-point, seconds. Exactly one of end / duration. Past the source it clamps and the result warns trim_clamped_to_source."},"duration":{"type":"number","minimum":0.2,"maximum":900,"description":"Length of the cut, seconds. Exactly one of end / duration."},"precision":{"type":"string","enum":["exact","keyframe"],"default":"exact","description":"exact re-encodes (frame-accurate libx264, yuv420p, what every timeline / caption / filter route accepts). keyframe stream-copies: faster and lossless, but the cut may start up to a GOP early — the result reports actual_start_seconds."},"audio":{"type":"string","enum":["keep","drop"],"default":"keep","description":"Keep the source audio (re-muxed as AAC on exact) or drop it."},"output":{"type":"object","additionalProperties":false,"description":"Optional conform on the way out (exact only; 400 video_trim_output_requires_exact on keyframe). Omit to inherit the source. Set it to the timeline you assemble into so the clip is not rescaled twice.","properties":{"width":{"type":"integer","minimum":256,"maximum":2160},"height":{"type":"integer","minimum":256,"maximum":2160},"fps":{"type":"number","enum":[24,25,30,60]}}},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeAudioDetachRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"description":"Sume Audio detach 1.0 request. Extracts the audio track of ONE Sume-hosted video into a NEW durable media.sume.com audio artifact — wav (pcm_s16le, sample-exact; what timeline_create audio.url, timeline_audio and the avatar mux want) by default, or mp3. The video is untouched. Optional single range; for many ranges detach once and split with POST /v1/timeline-1.0/audio. A source with no audio track fails detach_source_has_no_audio. The server compiles the ffmpeg, so there is no -i, argv, codec or filter field — sending one is 400 ffmpeg_fields_rejected. Max 1800 seconds of source and 900 seconds of output. Reserved at 6.4 credits per job, captured at the pass's own compute at list price, idle time included, never above the reservation.","properties":{"video_url":{"type":"string","format":"uri","description":"media.sume.com video already generated in this workspace. The audio is a new artifact URL; the video is not modified."},"format":{"type":"string","enum":["wav","mp3"],"default":"wav","description":"wav = pcm_s16le, sample-exact. mp3 = 128 kbps for hand-off or playback."},"range":{"type":"object","additionalProperties":false,"required":["start"],"description":"Optional sub-range, seconds. Omit for the whole track. end must be after start; open-ended when end is omitted.","properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","exclusiveMinimum":0}}},"channels":{"type":"string","enum":["source","mono"],"default":"source","description":"Keep the source channel layout, or downmix to mono."},"sample_rate":{"type":"integer","enum":[16000,44100,48000],"description":"Omit to inherit the source rate. 16000 with channels mono is the speech-to-text shape."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"SumeTimelinePlan":{"type":"object","additionalProperties":false,"required":["object","valid","duration_seconds","segment_count","coverage_seconds","billable_minutes","estimated_credits","transition_count","filtergraph_summary","warnings"],"description":"Unbilled timeline plan/check result. Validates schema + bounds and returns a compiled filtergraph summary without fetching media, creating a job, or reserving credits. Cannot predict short-source downgrade warnings.","properties":{"object":{"type":"string","enum":["timeline_plan"]},"valid":{"type":"boolean"},"duration_seconds":{"type":"number"},"segment_count":{"type":"integer"},"coverage_seconds":{"type":"number"},"billable_minutes":{"type":"integer"},"estimated_credits":{"type":"integer","minimum":0,"description":"Credits the render would reserve (billable_minutes × the per-minute rate)."},"estimated_usd":{"type":"string","description":"The same reservation in US dollars, rounded up to the cent: the figure to quote."},"transition_count":{"type":"integer"},"filtergraph_summary":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"segment_index":{"type":"integer"},"message":{"type":"string"},"context":{"type":"object","additionalProperties":true}}}}}},"SumeVideoGenerationRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"description":"Text prompt for Sume Video 1.0. Provider model ids are selected by Sume and are not accepted in this schema."},"image_url":{"type":"string","format":"uri","description":"Optional first-frame image URL for image-to-video generation."},"first_frame_url":{"type":"string","format":"uri","deprecated":true,"description":"Alias for image_url. Prefer image_url."},"end_image_url":{"type":"string","format":"uri","description":"Optional end-frame image URL. Requires image_url or first_frame_url."},"last_frame_url":{"type":"string","format":"uri","deprecated":true,"description":"Alias for end_image_url. Prefer end_image_url."},"reference_image_urls":{"type":"array","minItems":1,"maxItems":9,"items":{"type":"string","format":"uri"}},"reference_video_urls":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","format":"uri"}},"reference_audio_urls":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","format":"uri"},"description":"Reference audio URLs require at least one reference image or video."},"resolution":{"type":"string","enum":["480p","720p","768p","1080p","4k"],"description":"Legacy resolution vocabulary. The Auto serving family validates support; omit to use its default. 4k is rejected."},"duration":{"type":"integer","minimum":4,"maximum":30,"description":"Requested clip duration in seconds, validated against the Auto serving family. Prefer this field; duration_seconds is an accepted alias."},"duration_seconds":{"type":"integer","minimum":4,"maximum":30,"description":"Alias of duration. When both duration and duration_seconds are set, they must agree."},"bitrate_mode":{"type":"string","enum":["standard","high"]},"aspect_ratio":{"type":"string","enum":["auto","adaptive","21:9","16:9","4:3","1:1","3:4","9:16"]},"generate_audio":{"type":"boolean"},"routing_preset":{"deprecated":true,"type":"string","enum":["cost","speed","quality","grok","kling"],"description":"Retired routing hint, accepted for compatibility and ignored. All requests use Video Router Auto."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"RemixRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"properties":{"video_url":{"type":"string","format":"uri","description":"The source video, a public HTTPS URL, 4–15 s and at most 200 MiB. Its sound is kept on the output."},"image_urls":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","format":"uri"},"description":"1 to 8 public HTTPS image URLs, in order: the people, objects or look to use. The prompt can say which subject each image takes."},"reference_image_urls":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","format":"uri"},"deprecated":true,"description":"The older name of `image_urls`. Send one of the two."},"prompt":{"type":"string","maxLength":10000,"description":"Optional, any language. Say which subject of the source each image takes; a subject you do not name is matched by its position from the left."},"resolution":{"type":"string","enum":["480p","720p","1080p"],"default":"720p","description":"Output resolution. The aspect ratio follows the source."},"duration":{"type":"integer","minimum":4,"maximum":15,"description":"Optional: the source video's length in seconds, rounded up. Leave it out and the API reads it from the MP4 or MOV header. The output follows the source's length; the job bills by it."}}},"RemixRestylePresetsResponse":{"type":"object","additionalProperties":false,"required":["model","items"],"properties":{"model":{"type":"string"},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","preview_url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"preview_url":{"type":"string","format":"uri","description":"The style plate the edit uses as its reference image."}}}}}},"RemixRestyleRequest":{"type":"object","additionalProperties":false,"required":["video_url","preset_id"],"properties":{"video_url":{"type":"string","format":"uri","description":"The source video, a public HTTPS URL, 4–15 s and at most 200 MiB. Its sound is kept on the output."},"image_urls":{"type":"array","minItems":0,"maxItems":0,"items":{"type":"string","format":"uri"},"description":"Not taken: the style's plate and the source's first frame are the reference images. Leave it out or send []."},"reference_image_urls":{"type":"array","minItems":0,"maxItems":0,"items":{"type":"string","format":"uri"},"deprecated":true,"description":"The older name of `image_urls`. Send one of the two."},"prompt":{"type":"string","maxLength":10000,"description":"Optional, any language: added after the style's own prompt."},"resolution":{"type":"string","enum":["480p","720p","1080p"],"default":"720p","description":"Output resolution. The aspect ratio follows the source."},"duration":{"type":"integer","minimum":4,"maximum":15,"description":"Optional: the source video's length in seconds, rounded up. Leave it out and the API reads it from the MP4 or MOV header. The output follows the source's length; the job bills by it."},"preset_id":{"type":"string","enum":["cel-shaded-cg-anime","chunky-textured-low-poly","comic-3d","expressive-2d-animation","expressive-gouache-fashion","felt-puppet-stop-motion","graphic-cel","grotesque-street-cgi","hand-painted-cel-animation","knitted-yarn-world","neon-graphic-cinematic-3d","nighttime-anime-pixel-art","outline-free-cel","painterly-cinematic-3d","painterly-sculpted-animation","retro-game-3d","rounded-toy-cgi","sculptural-3d-fashion","textured-gouache-character-illustration","warm-painterly-3d-animation"],"description":"One style from `GET /v1/sume/remix/restyle/v1.0/presets`. The source's first frame is redrawn in that style, with the prompt, and the edit restyles a depth video of the source from that frame and the style's plate."}}},"RemixSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","remix"],"properties":{"request_id":{"type":"string"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}},"remix":{"type":"object","additionalProperties":false,"required":["product","mode","model"],"description":"The product and the mode this job runs.","properties":{"product":{"type":"string","enum":["Sume Remix Lite","Sume Remix"]},"mode":{"type":"string","enum":["restyle","object-swap","motion-transfer"]},"model":{"type":"string","enum":["sume-remix","sume-remix-lite"]}}}}}}},"SumeVideoRouterGenerationRequest":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"type":"string","enum":["higgsfield-genjutsu","higgsfield-genjutsu-object-swap","higgsfield-genjutsu-light","higgsfield-genjutsu-light-object-swap","seedance-2.5","seedance-2-mini","seedance-2","seedance-2-fast","kling-3","wan-3.0","grok-imagine-video-1.5","minimax-h3","minimax-h3-max","gemini-omni-flash-1.1","vidu-q4","vidu-q4-reference","veo-3.1","veo-3.1-fast","veo-3.1-lite","kling-4","kling-4-omni","wand-vega-1.0-lite","wand-vega-1.0-pro","wand-vega-1.5-pro","mingmou-1","hunyuan-1.5","hailuo-h3-regen","heygen-video-1","kling-2.6","kling-3-turbo","kling-3-omni","hailuo-2.3","hailuo-2.3-fast","happy-horse-1.0","happy-horse-1.1","wan-3.0-prime","higgsfield-cinema-studio-4","veed-fabric-1.0","veed-fabric-1.0-fast","kling-avatar-2.0-pro","kling-avatar-2.0","infinitalk","omnihuman-1.5","omnihuman-2","wan-2.2-speech-to-video","sync-lipsync-3","sync-lipsync-2-pro","sync-lipsync-2","kling-lipsync","latentsync","veed-lipsync","infinitalk-video","pixverse-lipsync","veed-subtitles","veed-dubbing","topaz-video","sam-3-video","luma-ray-2-flash-reframe","sumelabs/depth-anything-video","sumelabs/depth-anything-v3-video","sumelabs/wand","auto-","sume/auto","auto"],"description":"Video Router catalog model id, or `auto-` / `sume/auto` / `auto` to let Sume pick. Not accepted on Video 1.0."},"prompt":{"type":"string","minLength":1,"description":"Text prompt for the selected Video Router model. Optional on `auto-` / `sume/auto` / `auto`."},"task":{"type":"string","description":"Optional creative brief for `auto-`. Ignored on named catalog models."},"image_url":{"type":"string","format":"uri","description":"Optional first-frame image URL. Required for grok-imagine-video-1.5."},"first_frame_url":{"type":"string","format":"uri","deprecated":true,"description":"Alias for image_url. Prefer image_url."},"end_image_url":{"type":"string","format":"uri","description":"Optional end-frame image URL. Requires image_url or first_frame_url. Not supported by grok-imagine-video-1.5."},"last_frame_url":{"type":"string","format":"uri","deprecated":true,"description":"Alias for end_image_url. Prefer end_image_url."},"video_url":{"type":"string","format":"uri","description":"Source clip for video-to-video models. gemini-omni-flash-1.1 (edit): the prompt describes the edit, resolution is optional (default 720p), aspect_ratio is rejected and duration is not sent to the provider and does not set the price: an edit is charged for the clip's length read from the file, rounded up, at least 3 s and at most 10 s, at the output rate, plus a per-second source fee for up to 10 s (an unreadable clip is charged 10 s); cannot be combined with image_url / end_image_url / reference_*_urls — use reference_video_urls when the clip should condition a fresh generation instead. higgsfield-genjutsu (Motion Transfer) and higgsfield-genjutsu-object-swap (Object Swap) require video_url together with reference_image_urls and the inspected source duration; output keeps the source length. They are charged for every second of the source read from the file, rounded up (an unreadable clip is charged 30 s); duration is still checked but does not set the price."},"audio_url":{"type":"string","format":"uri","description":"Lipsync models only: the speech the face says (a public HTTPS audio file). Image rows (veed-fabric-1.0, kling-avatar-2.0, infinitalk, omnihuman-1.5, …) take image_url; video rows (sync-lipsync-3, kling-lipsync, latentsync, …) take video_url. duration is required: the clip's length in whole seconds (the audio's, for an image row)."},"dubbing":{"type":"object","additionalProperties":false,"required":["target_language"],"description":"Dubbing models only (veed-dubbing): says video_url's speech in target_language, in each speaker's cloned voice, with their lips synced. duration is required: the clip's length in whole seconds, rounded up (2-600). No prompt, resolution or aspect_ratio.","properties":{"target_language":{"type":"string","description":"The language to dub into, as a BCP 47 base tag such as ko (see the model's catalog constraints). Regional tags are not taken."},"source_language":{"type":"string","description":"The language spoken in the clip, as a BCP 47 base tag. Omit it, or send auto, to detect it."}}},"captions":{"type":"object","additionalProperties":false,"required":["style"],"description":"Caption models only (veed-subtitles): burns styled lines into video_url. duration is required: the clip's length in whole seconds (2-600, billed for at least 60). resolution is 1080p, the default.","properties":{"style":{"type":"string","description":"The caption style (see the model's catalog constraints). Dynamic styles bill twice."},"srt":{"type":"string","maxLength":100000,"description":"The lines as SRT text. Omit it and the clip's speech is transcribed."},"position":{"type":"string","enum":["top","center","bottom"],"description":"Where the lines sit on screen."},"shadow":{"type":"string","enum":["none","min","mid","max"],"description":"How strong the shadow behind the lines is. Omit it to keep the style's own."}}},"upscale":{"type":"object","additionalProperties":false,"description":"topaz-video only: upscales video_url, raises its frame rate, or both. resolution is the output's size (720p, 1080p or 4K for anything above 1080p, the default). duration is required: the clip's length in whole seconds, rounded up (2-60). Billed twice above 30 fps, and when fps is unsent.","properties":{"factor":{"type":"number","minimum":1,"maximum":4,"description":"How many times larger each side gets (default 2). Send 1 with fps for a frame-rate boost only."},"fps":{"type":"integer","minimum":16,"maximum":60,"description":"The output frame rate; the frames in between are interpolated. Omit it to keep the clip's own rate."},"model":{"type":"string","description":"The Topaz enhancement model (default Proteus; see the model's catalog constraints)."}}},"background":{"type":"object","additionalProperties":false,"description":"sam-3-video only: removes video_url's background, keeping what prompt names (such as the person). duration is required: the clip's length in whole seconds, rounded up (2-60).","properties":{"output":{"type":"string","enum":["cutout","mask"],"description":"cutout (default): the subject alone; mask: its mask."}}},"depth":{"type":"object","additionalProperties":false,"description":"sumelabs/depth-anything-v3-video only: how the depth map of video_url is drawn. duration is the clip's length in whole seconds, rounded up: required on sumelabs/depth-anything-video and sumelabs/depth-anything-v3-video (1-600); sumelabs/wand (WAND) reads it from video_url when left out (2-600) and takes no depth options.","properties":{"colormap":{"type":"string","enum":["grayscale","inferno","turbo"],"description":"grayscale (default; near is white, far is black), inferno or turbo."}}},"extend":{"type":"boolean","description":"seedance-2.5 only, with video_url: continue the clip instead of editing it. duration (4-30) is the length of the new part; the prompt says what happens next."},"source_duration":{"type":"integer","minimum":1,"maximum":30,"description":"seedance-2.5 with extend only: the length of video_url in whole seconds, rounded up. It prices the clip the model reads; unsent, the clip is priced as 15 s."},"draft":{"type":"boolean","description":"seedance-2.5 only: a 480p draft at the 480p price. duration is required; video_url is not accepted. Finish a draft you keep with draft_job_id."},"draft_job_id":{"type":"string","description":"seedance-2.5 only: the id of a completed draft job in this workspace. Makes the same scene at 1080p, priced as 1080p for the draft's length. Send only model, draft_job_id and optionally resolution 1080p; the prompt, references, duration and aspect ratio come from the draft."},"reference_image_urls":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"string","format":"uri"},"description":"Reference images. seedance-2.5 takes up to 30 (50 reference files in all); most other models up to 9 or 10. On higgsfield-genjutsu and higgsfield-genjutsu-object-swap, 1–8 Genjutsu references."},"reference_video_urls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"description":"Reference clips that condition a fresh generation (not the edit source — see video_url). seedance-2.5 takes up to 10, at most 30.2 seconds in all; most other models up to 3 or 5. gemini-omni-flash-1.1 accepts at most 3, each at most 3 seconds; address them in the prompt as <VIDEO_REF_0>, <VIDEO_REF_1>, ... (0-based, list order)."},"reference_audio_urls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"}},"resolution":{"type":"string","enum":["360p","480p","540p","720p","768p","1080p","2K","4K","4k","8K"],"description":"Defaults to provider/runtime defaults when omitted (typically 720p; MiniMax H3 / H3 Max default to 768p). Each model takes only the resolutions its catalog row lists in capabilities.resolutions — higgsfield-genjutsu, higgsfield-genjutsu-object-swap, higgsfield-genjutsu-light, higgsfield-genjutsu-light-object-swap, seedance-2.5, wan-3.0, wan-3.0-prime: 480p, 720p, 1080p; seedance-2-mini, seedance-2-fast, grok-imagine-video-1.5, higgsfield-cinema-studio-4, veed-fabric-1.0, veed-fabric-1.0-fast, infinitalk, wan-2.2-speech-to-video, infinitalk-video: 480p, 720p; seedance-2: 480p, 720p, 1080p, 4K; kling-3, kling-2.6, veed-subtitles: 1080p; minimax-h3: 768p, 2K, 4K; minimax-h3-max: 480p, 768p, 1080p; gemini-omni-flash-1.1: 360p, 720p, 1080p, 4K; vidu-q4, vidu-q4-reference: 540p, 720p, 1080p, 2K, 4K; veo-3.1, veo-3.1-fast, veo-3.1-lite, kling-4, kling-4-omni, kling-3-turbo, kling-3-omni, happy-horse-1.0, happy-horse-1.1: 720p, 1080p; wand-vega-1.0-lite: 768p, 1080p, 2K, 4K; wand-vega-1.0-pro, wand-vega-1.5-pro, mingmou-1, hunyuan-1.5: 720p, 1080p, 2K, 4K; hailuo-h3-regen: 2K; heygen-video-1: 480p, 768p, 1080p, 2K; hailuo-2.3, hailuo-2.3-fast: 768p, 1080p; kling-avatar-2.0-pro, kling-avatar-2.0, omnihuman-2, sync-lipsync-3, sync-lipsync-2-pro, sync-lipsync-2, kling-lipsync, latentsync, veed-lipsync, pixverse-lipsync, veed-dubbing, sam-3-video, luma-ray-2-flash-reframe, sumelabs/depth-anything-video, sumelabs/depth-anything-v3-video: ; omnihuman-1.5: 720p; topaz-video: 720p, 1080p, 4K; sumelabs/wand: 720p, 1080p, 2K, 4K, 8K. Aliases: seedance-2, minimax-h3, gemini-omni-flash-1.1, vidu-q4, vidu-q4-reference, wand-vega-1.0-lite, wand-vega-1.0-pro, wand-vega-1.5-pro, mingmou-1, hunyuan-1.5, topaz-video, sumelabs/wand also accept 4k (renders 4K); kling-3 also accept 720p (renders 1080p). 768p is MiniMax H3 / H3 Max native; minimax-h3-max 1080p is latent refinement from native 768p, and minimax-h3 2K / 4K are 768p upscales. sumelabs/wand (WAND depth) is priced by the clip's size, 720p, 1080p, 2K, 4K or 8K by its shorter side, which the API reads from video_url; send resolution only when the file cannot be read."},"duration":{"anyOf":[{"type":"integer","minimum":1,"maximum":600},{"type":"string","enum":["auto"]}],"description":"Requested clip duration in seconds. wan-3.0 accepts 2-30; seedance-2.5 accepts 4-30; MiniMax H3 / H3 Max accept 5-15; gemini-omni-flash-1.1 accepts 3-10 (default 8; ignored by the provider on edit); higgsfield-genjutsu and higgsfield-genjutsu-object-swap require the source length, 4-30; veo-3.1 / veo-3.1-fast / veo-3.1-lite accept 4, 6 or 8 (default 8); WAND-Vega 1.0 Lite / 1.0 Pro / 1.5 Pro accept 4-15 (default 5); mingmou-1 accepts 5 or 10; hunyuan-1.5 accepts 5; hailuo-h3-regen requires the source length, 5-16 (rounded up; reserve-only, output keeps the source length); heygen-video-1 accepts 5-30 or auto (default 5; over 15 s for text or a first frame only); lipsync models require the clip's length (the audio's, for an image row), each within its catalog range, up to 60; veed-subtitles and veed-dubbing require the source clip's length, 2-600; topaz-video, sam-3-video and depth-anything-video require the source clip's length, 2-60; luma-ray-2-flash-reframe requires it, 2-10; every other model is capped at 15."},"duration_seconds":{"type":"integer","minimum":2,"maximum":600,"description":"Alias of duration."},"bitrate_mode":{"type":"string","enum":["standard","high"]},"aspect_ratio":{"type":"string","enum":["auto","adaptive","21:9","16:9","4:3","1:1","3:4","9:16"]},"generate_audio":{"type":"boolean"},"frame_images":{"type":"array","maxItems":2,"description":"First/last frames. Accepted on `auto-` in addition to `image_url`.","items":{"type":"object","additionalProperties":false,"required":["type","image_url","frame_type"],"properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"frame_type":{"type":"string","enum":["first_frame","last_frame"]}}}},"input_references":{"type":"array","maxItems":20,"description":"Reference assets. Accepted on `auto-` in addition to `reference_*_urls`.","items":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["image_url","audio_url","video_url"]},"image_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"audio_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"video_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"model_params":{"type":"object","additionalProperties":false,"description":"Reserved for per-model knobs. Empty allowlist in v1 — omit or send {}."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook","text_to_video","image_to_video","reference_to_video","t2v","i2v","ref2va"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook. On heygen-video-1, HeyGen's generation modes text_to_video, image_to_video and reference_to_video (or t2v, i2v, ref2va) are accepted here too and must match the inputs; the job then runs async."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."},"prompt_enhancement":{"type":"string","enum":["turbo","quality","ultraquality","disabled","default"],"description":"heygen-video-1 only: HeyGen's prompt enhancement. turbo is fastest, quality (HeyGen's default) is balanced, ultraquality is slowest and best, disabled sends the prompt as written; default is HeyGen's alias for turbo. Over 15 s needs turbo, quality or default."},"seed":{"type":"integer","minimum":0,"maximum":4294967295,"description":"heygen-video-1 only: HeyGen's generation seed (unsigned 32-bit). The same prompt and seed return the same clip; random when omitted. Every other model refuses it."},"end_user_id":{"type":"string","minLength":1,"maxLength":128,"description":"heygen-video-1 only: HeyGen's opaque end-user id (1–128 characters, no spaces, no personal data), forwarded for HeyGen's usage attribution and abuse checks. It does not change the price."},"callback_id":{"type":"string","maxLength":256,"description":"heygen-video-1 only: HeyGen's client tracking id. Sume stores it as metadata.callback_id, which the job and its webhook echo."},"image":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"heygen-video-1 only: HeyGen's name for image_url, the first frame (image_to_video)."},"reference_images":{"type":"array","maxItems":9,"items":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"An https URL, or HeyGen's {\"type\":\"url\",\"url\":\"https://…\"}. HeyGen's asset_id and base64 forms name files inside HeyGen's own workspace: upload with POST /v1/assets and send the URL instead (a 400 says so)."},"description":"heygen-video-1 only: HeyGen's name for reference_image_urls (up to 9; <Picture 1>, <Picture 2>… in the prompt)."},"reference_videos":{"type":"array","maxItems":3,"items":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"An https URL, or HeyGen's {\"type\":\"url\",\"url\":\"https://…\"}. HeyGen's asset_id and base64 forms name files inside HeyGen's own workspace: upload with POST /v1/assets and send the URL instead (a 400 says so)."},"description":"heygen-video-1 only: HeyGen's name for reference_video_urls (up to 3, sharing a 15 s budget; <Video 1>… in the prompt)."},"reference_audio":{"type":"array","maxItems":3,"items":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"An https URL, or HeyGen's {\"type\":\"url\",\"url\":\"https://…\"}. HeyGen's asset_id and base64 forms name files inside HeyGen's own workspace: upload with POST /v1/assets and send the URL instead (a 400 says so)."},"description":"heygen-video-1 only: HeyGen's name for reference_audio_urls (up to 3; a voice line here is spoken with lip-sync)."}}},"VideoGenerationRequest":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"type":"string","description":"Catalog model id from GET /v1/videos/models. The same ids work on the legacy Video Router surface. `auto-` (aliases `sume/auto`, `auto`) lets Sume pick the family."},"prompt":{"type":"string","minLength":1,"description":"Text description of the video to generate. Optional on `auto-` / `sume/auto` / `auto`."},"task":{"type":"string","description":"Optional creative brief for `auto-`. Ignored on named catalog models."},"duration":{"anyOf":[{"type":"integer","minimum":1,"maximum":600},{"type":"string","enum":["auto"]}],"description":"Duration of the generated video in seconds. heygen-video-1 also takes \"auto\": HeyGen sizes the clip to the quoted dialogue (8 s minimum)."},"resolution":{"type":"string","enum":["360p","480p","540p","720p","768p","1080p","1K","2K","4K"],"description":"Output resolution. Must be advertised in the model's supported_resolutions. Each model takes only the resolutions its catalog row lists in capabilities.resolutions — higgsfield-genjutsu, higgsfield-genjutsu-object-swap, higgsfield-genjutsu-light, higgsfield-genjutsu-light-object-swap, seedance-2.5, wan-3.0, wan-3.0-prime: 480p, 720p, 1080p; seedance-2-mini, seedance-2-fast, grok-imagine-video-1.5, higgsfield-cinema-studio-4, veed-fabric-1.0, veed-fabric-1.0-fast, infinitalk, wan-2.2-speech-to-video, infinitalk-video: 480p, 720p; seedance-2: 480p, 720p, 1080p, 4K; kling-3, kling-2.6, veed-subtitles: 1080p; minimax-h3: 768p, 2K, 4K; minimax-h3-max: 480p, 768p, 1080p; gemini-omni-flash-1.1: 360p, 720p, 1080p, 4K; vidu-q4, vidu-q4-reference: 540p, 720p, 1080p, 2K, 4K; veo-3.1, veo-3.1-fast, veo-3.1-lite, kling-4, kling-4-omni, kling-3-turbo, kling-3-omni, happy-horse-1.0, happy-horse-1.1: 720p, 1080p; wand-vega-1.0-lite: 768p, 1080p, 2K, 4K; wand-vega-1.0-pro, wand-vega-1.5-pro, mingmou-1, hunyuan-1.5: 720p, 1080p, 2K, 4K; hailuo-h3-regen: 2K; heygen-video-1: 480p, 768p, 1080p, 2K; hailuo-2.3, hailuo-2.3-fast: 768p, 1080p; kling-avatar-2.0-pro, kling-avatar-2.0, omnihuman-2, sync-lipsync-3, sync-lipsync-2-pro, sync-lipsync-2, kling-lipsync, latentsync, veed-lipsync, pixverse-lipsync, veed-dubbing, sam-3-video, luma-ray-2-flash-reframe, sumelabs/depth-anything-video, sumelabs/depth-anything-v3-video: ; omnihuman-1.5: 720p; topaz-video: 720p, 1080p, 4K; sumelabs/wand: 720p, 1080p, 2K, 4K, 8K. Aliases: seedance-2, minimax-h3, gemini-omni-flash-1.1, vidu-q4, vidu-q4-reference, wand-vega-1.0-lite, wand-vega-1.0-pro, wand-vega-1.5-pro, mingmou-1, hunyuan-1.5, topaz-video, sumelabs/wand also accept 4k (renders 4K); kling-3 also accept 720p (renders 1080p)."},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4","3:2","2:3","21:9","9:21","auto","adaptive"],"description":"Output aspect ratio. Must be advertised in the model's supported_aspect_ratios. `auto` / `adaptive` are accepted on `auto-`."},"size":{"type":"string","pattern":"^\\d+x\\d+$","description":"Exact pixel dimensions as WIDTHxHEIGHT. Not supported in v1: every model reports supported_sizes: null, so sending it returns 400. Use resolution + aspect_ratio."},"frame_images":{"type":"array","maxItems":2,"description":"First/last frame images for image-to-video. Takes precedence over input_references when both are sent.","items":{"type":"object","additionalProperties":false,"required":["type","image_url","frame_type"],"properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"frame_type":{"type":"string","enum":["first_frame","last_frame"]}}}},"input_references":{"type":"array","maxItems":15,"description":"Reference assets for reference-to-video. Types must be advertised in the model's supported_input_references.","items":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["image_url","audio_url","video_url"]},"image_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"audio_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"video_url":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"generate_audio":{"type":"boolean","description":"Generate an audio track alongside the video. Defaults to the model's audio capability."},"callback_url":{"type":"string","format":"uri","description":"HTTPS webhook destination for the terminal job event. Sume delivers its standard job webhook envelope."},"provider":{"type":"object","additionalProperties":false,"description":"Provider passthrough configuration. Not supported in v1: allowed_passthrough_parameters is empty for every model, so a non-empty options object returns 400.","properties":{"options":{"type":"object","additionalProperties":true}}},"image_url":{"type":"string","format":"uri","description":"Video Router first-frame URL. Accepted on `auto-` in addition to `frame_images`."},"first_frame_url":{"type":"string","format":"uri","description":"Alias for image_url. Accepted on `auto-`."},"end_image_url":{"type":"string","format":"uri","description":"End-frame URL. Accepted on `auto-`."},"last_frame_url":{"type":"string","format":"uri","description":"Alias for end_image_url. Accepted on `auto-`."},"video_url":{"type":"string","format":"uri","description":"Edit source clip. Accepted on `auto-`; decide routes it to a family that supports video-to-video."},"reference_image_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Reference stills. Accepted on `auto-`."},"reference_video_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Reference clips. Accepted on `auto-`."},"reference_audio_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Reference audio. Accepted on `auto-`."},"mode":{"type":"string","enum":["text_to_video","image_to_video","reference_to_video","t2v","i2v","ref2va"],"description":"heygen-video-1 only: HeyGen's generation mode. Optional: Sume reads it from the inputs (a first frame is image_to_video, references are reference_to_video). When sent it must match them."},"prompt_enhancement":{"type":"string","enum":["turbo","quality","ultraquality","disabled","default"],"description":"heygen-video-1 only: HeyGen's prompt enhancement. turbo is fastest, quality (HeyGen's default) is balanced, ultraquality is slowest and best, disabled sends the prompt as written; default is HeyGen's alias for turbo. Over 15 s needs turbo, quality or default."},"seed":{"type":"integer","minimum":0,"maximum":4294967295,"description":"heygen-video-1 only: HeyGen's generation seed (unsigned 32-bit). The same prompt and seed return the same clip; random when omitted. Every other model refuses it."},"end_user_id":{"type":"string","minLength":1,"maxLength":128,"description":"heygen-video-1 only: HeyGen's opaque end-user id (1–128 characters, no spaces, no personal data), forwarded for HeyGen's usage attribution and abuse checks. It does not change the price."},"callback_id":{"type":"string","maxLength":256,"description":"heygen-video-1 only: HeyGen's client tracking id. Sume stores it as metadata.callback_id, which the job and its webhook echo."},"image":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"heygen-video-1 only: HeyGen's name for image_url, the first frame (image_to_video)."},"reference_images":{"type":"array","maxItems":9,"items":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"An https URL, or HeyGen's {\"type\":\"url\",\"url\":\"https://…\"}. HeyGen's asset_id and base64 forms name files inside HeyGen's own workspace: upload with POST /v1/assets and send the URL instead (a 400 says so)."},"description":"heygen-video-1 only: HeyGen's name for reference_image_urls (up to 9; <Picture 1>, <Picture 2>… in the prompt)."},"reference_videos":{"type":"array","maxItems":3,"items":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"An https URL, or HeyGen's {\"type\":\"url\",\"url\":\"https://…\"}. HeyGen's asset_id and base64 forms name files inside HeyGen's own workspace: upload with POST /v1/assets and send the URL instead (a 400 says so)."},"description":"heygen-video-1 only: HeyGen's name for reference_video_urls (up to 3, sharing a 15 s budget; <Video 1>… in the prompt)."},"reference_audio":{"type":"array","maxItems":3,"items":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["url","asset_id","base64"]},"url":{"type":"string","format":"uri","maxLength":2048}}}],"description":"An https URL, or HeyGen's {\"type\":\"url\",\"url\":\"https://…\"}. HeyGen's asset_id and base64 forms name files inside HeyGen's own workspace: upload with POST /v1/assets and send the URL instead (a 400 says so)."},"description":"heygen-video-1 only: HeyGen's name for reference_audio_urls (up to 3; a voice line here is spoken with lip-sync)."}}},"VideoGenerationResponse":{"type":"object","additionalProperties":false,"description":"Video generation job. Bare object, not Sume's { data: ... } envelope — the same job stays readable in Sume shape at GET /v1/jobs/{id}/status.","required":["id","polling_url","status"],"properties":{"id":{"type":"string","description":"Job identifier."},"polling_url":{"type":"string","description":"Absolute URL to poll until the job reaches a terminal state."},"status":{"type":"string","enum":["pending","in_progress","completed","failed","cancelled","expired"]},"generation_id":{"type":"string","description":"Generation identifier. Sume has one id per job, so this equals `id`."},"model":{"type":"string","description":"The requested model, echoed verbatim. `sume/auto` stays `sume/auto`."},"unsigned_urls":{"type":"array","items":{"type":"string"},"description":"Content URLs for the generated videos, once completed."},"usage":{"type":"object","additionalProperties":false,"required":["credits","is_byok"],"properties":{"credits":{"type":"integer","minimum":0,"nullable":true,"description":"Credits this generation is charged: the hold while the job runs, then what the wallet kept."},"is_byok":{"type":"boolean","description":"True only on jobs from before 2026-10-25 that a workspace's own provider key paid for; credits were then the Sume share only. Always false on new jobs."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"error":{"type":"string","description":"Failure message, when status is failed."}}},"VideoModel":{"type":"object","additionalProperties":false,"required":["id","canonical_slug","name","description","created","supported_resolutions","supported_aspect_ratios","supported_sizes","supported_durations","supported_frame_images","supported_input_references","generate_audio","seed","sku_credits","allowed_passthrough_parameters","hugging_face_id"],"properties":{"id":{"type":"string","enum":["higgsfield-genjutsu","higgsfield-genjutsu-object-swap","higgsfield-genjutsu-light","higgsfield-genjutsu-light-object-swap","seedance-2.5","seedance-2-mini","seedance-2","seedance-2-fast","kling-3","wan-3.0","grok-imagine-video-1.5","minimax-h3","minimax-h3-max","gemini-omni-flash-1.1","vidu-q4","vidu-q4-reference","veo-3.1","veo-3.1-fast","veo-3.1-lite","kling-4","kling-4-omni","wand-vega-1.0-lite","wand-vega-1.0-pro","wand-vega-1.5-pro","mingmou-1","hunyuan-1.5","hailuo-h3-regen","heygen-video-1","kling-2.6","kling-3-turbo","kling-3-omni","hailuo-2.3","hailuo-2.3-fast","happy-horse-1.0","happy-horse-1.1","wan-3.0-prime","higgsfield-cinema-studio-4","veed-fabric-1.0","veed-fabric-1.0-fast","kling-avatar-2.0-pro","kling-avatar-2.0","infinitalk","omnihuman-1.5","omnihuman-2","wan-2.2-speech-to-video","sync-lipsync-3","sync-lipsync-2-pro","sync-lipsync-2","kling-lipsync","latentsync","veed-lipsync","infinitalk-video","pixverse-lipsync"]},"canonical_slug":{"type":"string","enum":["higgsfield-genjutsu","higgsfield-genjutsu-object-swap","higgsfield-genjutsu-light","higgsfield-genjutsu-light-object-swap","seedance-2.5","seedance-2-mini","seedance-2","seedance-2-fast","kling-3","wan-3.0","grok-imagine-video-1.5","minimax-h3","minimax-h3-max","gemini-omni-flash-1.1","vidu-q4","vidu-q4-reference","veo-3.1","veo-3.1-fast","veo-3.1-lite","kling-4","kling-4-omni","wand-vega-1.0-lite","wand-vega-1.0-pro","wand-vega-1.5-pro","mingmou-1","hunyuan-1.5","hailuo-h3-regen","heygen-video-1","kling-2.6","kling-3-turbo","kling-3-omni","hailuo-2.3","hailuo-2.3-fast","happy-horse-1.0","happy-horse-1.1","wan-3.0-prime","higgsfield-cinema-studio-4","veed-fabric-1.0","veed-fabric-1.0-fast","kling-avatar-2.0-pro","kling-avatar-2.0","infinitalk","omnihuman-1.5","omnihuman-2","wan-2.2-speech-to-video","sync-lipsync-3","sync-lipsync-2-pro","sync-lipsync-2","kling-lipsync","latentsync","veed-lipsync","infinitalk-video","pixverse-lipsync"]},"name":{"type":"string"},"description":{"type":"string"},"created":{"type":"integer","description":"Catalog publication date as a Unix timestamp, not a provider release date."},"supported_resolutions":{"type":"array","items":{"type":"string"}},"supported_aspect_ratios":{"type":"array","items":{"type":"string"}},"supported_sizes":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Always null in v1 — use resolution + aspect_ratio."},"supported_durations":{"type":"array","items":{"type":"integer"}},"supported_durations_by_mode":{"type":"object","additionalProperties":false,"description":"Duration range per generation mode, where a mode allows a different range than duration_seconds (heygen-video-1: references cap at 15 s).","properties":{"text_to_video":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"image_to_video":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"reference_to_video":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}},"supported_frame_images":{"type":"array","items":{"type":"string","enum":["first_frame","last_frame"]}},"supported_input_references":{"type":"array","items":{"type":"string","enum":["image_url","audio_url","video_url"]}},"generate_audio":{"type":"boolean"},"seed":{"type":"boolean"},"sku_credits":{"type":"object","additionalProperties":{"type":"number","minimum":0},"description":"Credits per SKU unit (two decimals, rounded up), keyed by SKU."},"pricing_skus":{"type":"object","additionalProperties":{"type":"string"},"description":"On a model open.sume.com sells: US dollars per SKU unit as decimal strings, the same keys as sku_credits and Open's price. Absent on a model Open does not sell."},"allowed_passthrough_parameters":{"type":"array","items":{"type":"string"},"description":"Empty in v1 — provider.options is rejected."},"hugging_face_id":{"type":"string","nullable":true}}},"VideoModelsResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoModel"}}}},"VideoRouterCatalogItem":{"type":"object","additionalProperties":false,"required":["id","name","modality","routing","capabilities","pricing","constraints"],"properties":{"id":{"type":"string","enum":["higgsfield-genjutsu","higgsfield-genjutsu-object-swap","higgsfield-genjutsu-light","higgsfield-genjutsu-light-object-swap","seedance-2.5","seedance-2-mini","seedance-2","seedance-2-fast","kling-3","wan-3.0","grok-imagine-video-1.5","minimax-h3","minimax-h3-max","gemini-omni-flash-1.1","vidu-q4","vidu-q4-reference","veo-3.1","veo-3.1-fast","veo-3.1-lite","kling-4","kling-4-omni","wand-vega-1.0-lite","wand-vega-1.0-pro","wand-vega-1.5-pro","mingmou-1","hunyuan-1.5","hailuo-h3-regen","heygen-video-1","kling-2.6","kling-3-turbo","kling-3-omni","hailuo-2.3","hailuo-2.3-fast","happy-horse-1.0","happy-horse-1.1","wan-3.0-prime","higgsfield-cinema-studio-4","veed-fabric-1.0","veed-fabric-1.0-fast","kling-avatar-2.0-pro","kling-avatar-2.0","infinitalk","omnihuman-1.5","omnihuman-2","wan-2.2-speech-to-video","sync-lipsync-3","sync-lipsync-2-pro","sync-lipsync-2","kling-lipsync","latentsync","veed-lipsync","infinitalk-video","pixverse-lipsync","veed-subtitles","veed-dubbing","topaz-video","sam-3-video","luma-ray-2-flash-reframe","sumelabs/depth-anything-video","sumelabs/depth-anything-v3-video","sumelabs/wand"]},"name":{"type":"string"},"modality":{"type":"string","enum":["video"]},"routing":{"type":"string","enum":["pass_through"]},"gated":{"type":"boolean","description":"When true, the model is omitted from public listings until GA."},"capabilities":{"type":"object","additionalProperties":false,"required":["text_to_video","image_to_video","end_frame","reference_images","reference_videos","reference_audios","video_to_video","audio","resolutions","duration_seconds","aspect_ratios"],"properties":{"text_to_video":{"type":"boolean"},"image_to_video":{"type":"boolean"},"end_frame":{"type":"boolean"},"reference_images":{"type":"boolean"},"reference_videos":{"type":"boolean"},"reference_audios":{"type":"boolean"},"video_to_video":{"type":"boolean","description":"Edit (video-to-video): the model accepts a single video_url source clip rewritten by prompt. Currently gemini-omni-flash-1.1 only."},"audio":{"type":"boolean"},"lipsync":{"type":"boolean","description":"Lipsync: the model makes a face say audio_url (the speech). An image row takes image_url, a video row takes video_url; duration is the clip's length."},"captions":{"type":"boolean","description":"Captions: the model burns styled lines (captions.style, captions.srt) into video_url; duration is the clip's length."},"resolutions":{"type":"array","items":{"type":"string"}},"duration_seconds":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"aspect_ratios":{"type":"array","items":{"type":"string"}},"duration_seconds_by_mode":{"type":"object","additionalProperties":false,"description":"Duration range per generation mode, where a mode allows a different range than duration_seconds (heygen-video-1: references cap at 15 s).","properties":{"text_to_video":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"image_to_video":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"reference_to_video":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}},"seed":{"type":"boolean","description":"The model takes seed in this environment (heygen-video-1 where HeyGen's own API serves it)."}}},"pricing":{"type":"object","additionalProperties":false,"description":"Credits per unit on this model (two decimals, rounded up); a request is charged its whole total once, rounded up. Token-priced models use credits_per_1000_video_tokens; per-second models use credits_per_second (and credits_per_second_audio_on when audio changes the rate); resolution-tiered models use credits_per_second_by_resolution.","required":["basis"],"properties":{"basis":{"type":"string","enum":["per_1000_video_tokens","per_second","per_second_by_resolution"]},"credits_per_1000_video_tokens":{"type":"number","minimum":0},"credits_per_second":{"type":"number","minimum":0},"credits_per_second_audio_on":{"type":"number","minimum":0},"credits_per_second_by_resolution":{"type":"object","additionalProperties":{"type":"number","minimum":0},"description":"Credits per second, keyed by resolution (e.g. 480p, 720p, 768p, 1080p, 2K, 4K)."},"usd_per_second":{"type":"string","pattern":"^\\d+\\.\\d{4,}$","description":"On a model Open sells: credits_per_second in US dollars, Open's price."},"usd_per_second_audio_on":{"type":"string","pattern":"^\\d+\\.\\d{4,}$","description":"On a model Open sells: credits_per_second_audio_on in US dollars."},"usd_per_second_by_resolution":{"type":"object","additionalProperties":{"type":"string","pattern":"^\\d+\\.\\d{4,}$"},"description":"On a model Open sells: US dollars per second, keyed by resolution, Open's price."},"usd_options":{"type":"array","description":"On a model open.sume.com sells: each option's rate in US dollars per unit (Open's own decimal string), the price www charges for it. The figures to quote to a person. Absent on a model Open does not sell; dry_run gives that model's charge.","items":{"type":"object","additionalProperties":false,"required":["label","usd"],"properties":{"label":{"type":"string"},"resolution":{"type":"string"},"audio":{"type":"boolean"},"quality":{"type":"string"},"usd":{"type":"string","pattern":"^\\d+\\.\\d{4,}$"}}}}}},"constraints":{"type":"array","items":{"type":"string"}}}},"VideoRouterModelsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/VideoRouterCatalogItem"}}}}}},"VideoRouterModelResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"$ref":"#/components/schemas/VideoRouterCatalogItem"}}}}},"ModelRunResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job"],"additionalProperties":true,"properties":{"request_id":{"type":"string"},"model":{"type":"string","description":"Sume-owned public model id for workflow-shaped model responses."},"run":{"type":"object","additionalProperties":true,"description":"Sume-owned model run envelope with polling, result, event, and cancel URLs."},"resources":{"type":"object","additionalProperties":true,"description":"Durable Sume resources created or reused by the model run."},"output":{"type":"object","nullable":true,"additionalProperties":true,"description":"Terminal Sume output when available. Pending async runs return null."},"steps":{"type":"array","description":"Public workflow steps. Steps expose Sume concepts only and omit raw provider ids, task ids, and provider URLs.","items":{"type":"object","additionalProperties":true}},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"status_url":{"type":"string","format":"uri","description":"Sume-owned job status URL when returned."},"result_url":{"type":"string","format":"uri","description":"Sume-owned job result URL when returned."},"events_url":{"type":"string","format":"uri","description":"Sume-owned job lifecycle events URL when returned."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"Sume-owned job cancel URL when the job is cancelable."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}},"avatar_id":{"type":"string","description":"Read-only durable avatar resource id returned after creation. Use `avatar_handle` in launch generation requests."},"avatar":{"$ref":"#/components/schemas/PublicDeveloperApiAvatar"},"avatar_video_id":{"type":"string","description":"Present for resource-backed Avatar Video 1.0 model runs."},"avatar_video":{"$ref":"#/components/schemas/PublicAvatarVideo"},"avatar_face_swap_id":{"type":"string","description":"Present for resource-backed Avatar Face Swap 1.0 beta model runs."},"avatar_face_swap":{"$ref":"#/components/schemas/PublicAvatarFaceSwap"}}}},"description":"Model-run submission envelope for canonical Sume-owned model endpoints. Resource-backed models such as Avatar 1.0 return their resource submit envelope plus the same Sume job lifecycle URLs."},"JobStatusResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job_id","status","sume_status","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","queue","queue_position","logs_available"],"properties":{"request_id":{"type":"string"},"job_id":{"type":"string"},"status":{"type":"string","enum":["IN_QUEUE","IN_PROGRESS","COMPLETED","FAILED","CANCELED"]},"sume_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"queue":{"type":"object","required":["state","reason","position","available_at","retry_after_seconds","runtime"],"properties":{"state":{"type":"string","enum":["waiting","deferred","runtime_unavailable","processing","completed","failed","canceled"]},"reason":{"type":"string","description":"Provider-neutral reason for the current queue state."},"position":{"type":"integer","nullable":true,"description":"Null until Sume computes real queue rank. The API does not return fake queue positions."},"available_at":{"type":"string","format":"date-time","description":"Earliest time the job is eligible for worker pickup or retry."},"retry_after_seconds":{"type":"integer","nullable":true},"runtime":{"type":"object","required":["job_ledger_configured","worker_configured","worker_heartbeat"],"properties":{"job_ledger_configured":{"type":"boolean"},"worker_configured":{"type":"boolean"},"worker_heartbeat":{"type":"object","required":["status","last_seen_at","stale_after_seconds"],"properties":{"status":{"type":"string","enum":["fresh","stale","missing"]},"last_seen_at":{"type":"string","format":"date-time","nullable":true},"stale_after_seconds":{"type":"integer"}},"description":"Provider-neutral worker liveness summary. Raw worker identifiers and internal topology are not exposed."}}}}},"queue_position":{"type":"integer","nullable":true,"description":"Null until Sume computes real queue rank. The API does not return fake queue positions."},"logs_available":{"type":"boolean","description":"False while Sume exposes lifecycle diagnostics through `events_url` instead of inline logs."},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"JobResultResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","job_id","status","result","linked_resource","job"],"properties":{"request_id":{"type":"string"},"job_id":{"type":"string"},"status":{"type":"string","enum":["COMPLETED"]},"result":{"$ref":"#/components/schemas/JobResultPayload"},"linked_resource":{"$ref":"#/components/schemas/PublicLinkedResource"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"WebhookEvent":{"type":"object","description":"Terminal callback payload delivered to `webhook_url`. Sume signs the raw JSON body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature`; receivers should return any 2xx status after durable processing.","required":["event","request_id","job_id","status","payload"],"properties":{"event":{"type":"string","enum":["job.completed","job.failed","job.canceled"]},"request_id":{"type":"string"},"job_id":{"type":"string"},"status":{"type":"string","enum":["OK","ERROR"]},"payload":{"$ref":"#/components/schemas/JobResultPayload"},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"example":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"PublicDeveloperApiAvatar":{"type":"object","required":["id","status","resource_status","type","source_type","handle","preview_image_url","preview_video_url","artifacts","metadata","voice","error","created_at","updated_at","ready_at","failed_at","archived_at","job","job_status"],"properties":{"id":{"type":"string","description":"Durable avatar resource id."},"status":{"type":"string","enum":["processing","ready","failed","archived"],"description":"Resource state. processing means the linked job is queued or running; ready means public Sume-hosted image data is available."},"resource_status":{"type":"string","enum":["processing","ready","failed","archived"],"description":"Canonical avatar resource state. This intentionally uses `ready` rather than job-level `completed` when the avatar image is usable."},"type":{"type":"string","enum":["prompt","photo","props"]},"source_type":{"type":"string","enum":["prompt","photo","props"]},"handle":{"type":"string","pattern":"^(?=.{2,30}$)(?![._])(?!.*[._]$)(?!.*[._]{2})[a-z0-9._]+$","description":"Instagram-style avatar handle stored without @. Allows lowercase letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Representative public Sume-hosted avatar image URL when ready. Raw provider URLs are never returned."},"preview_video_url":{"type":"string","format":"uri","nullable":true,"description":"Representative public Sume-hosted avatar preview video URL when ready. Null when no public-safe preview video artifact is available yet."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicArtifact"}},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarProfileMetadata"},{"type":"null"}],"description":"Public-safe text-complete avatar profile metadata for search and agent selection. Null until metadata has been backfilled or curated."},"voice":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"type":"string","enum":["processing","ready","failed"],"description":"Provider-neutral voice preparation state. Internal voice provider ids are never returned — an avatar whose voice is `ready` is the selector POST /v1/tts-1.0/generate resolves from `avatar_id` / `avatar_handle`, so a caller reaches a TTS voice without ever holding a voice id."}}},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"ready_at":{"type":"string","format":"date-time","nullable":true},"failed_at":{"type":"string","format":"date-time","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"job":{"type":"object","required":["id","status","status_url","result_url"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"}}},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true,"description":"Underlying Sume job lifecycle status, or null if no linked job is available."}}},"AvatarResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["avatar","job"],"properties":{"avatar":{"$ref":"#/components/schemas/PublicDeveloperApiAvatar"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"AvatarSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","avatar_id","avatar","job","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits"],"properties":{"request_id":{"type":"string"},"avatar_id":{"type":"string","description":"Read-only durable avatar resource id returned after creation. Use `avatar_handle` in launch generation requests."},"avatar":{"$ref":"#/components/schemas/PublicDeveloperApiAvatar"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"AvatarModelRunRequest":{"type":"object","additionalProperties":false,"required":["avatar_handle","input"],"properties":{"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive. User-created avatars cannot use the reserved `sume_` prefix; that namespace is reserved for Sume system/default avatars."},"input":{"oneOf":[{"type":"object","required":["type","prompt"],"properties":{"type":{"type":"string","enum":["prompt"]},"prompt":{"type":"string","minLength":1}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"type":"string","enum":["photo"]},"image_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS avatar photo URL. Localhost, private-network, non-HTTPS, and non-image responses are rejected before generation submission."}}},{"type":"object","required":["type","ethnicity","sex","age"],"properties":{"type":{"type":"string","enum":["props"]},"ethnicity":{"type":"string","enum":["Asian","South Asian","Southeast Asian","Black","Hispanic","Middle Eastern","White","Wasian"]},"sex":{"type":"string","enum":["male","female"]},"age":{"type":"integer","minimum":20,"maximum":80}}}]},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Canonical Sume Avatar 1.0 creation request. Avatar Video generation is a separate model-run endpoint."},"AvatarFaceSwapCreateRequest":{"type":"object","additionalProperties":false,"required":["avatar_handle","video_url","quality"],"properties":{"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."},"video_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS source video URL. Beta worker validation will require a source video suitable for face-swap processing, currently planned for 4-15 seconds with usable audio. Localhost, private-network, non-HTTPS, signed/private URLs, provider task URLs, transcripts, prompts, and provider fields are not part of this public contract."},"quality":{"type":"string","enum":["standard","plus","max"],"description":"Required beta quality selector. Supported values match Sume Avatar Video tiers: `standard`, `plus`, and `max`."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Strict beta Sume Avatar Face Swap 1.0 request. The contract accepts an existing ready avatar handle and a public source video URL only; avatar ids, prompts, transcripts, duration, aspect ratio, generated audio flags, and provider fields are intentionally unsupported."},"PublicAvatarFaceSwap":{"type":"object","required":["id","avatar_id","request_id","status","resource_status","job_status","created_at","updated_at","completed_at","video_url","artifacts","result","error"],"properties":{"id":{"type":"string"},"avatar_id":{"type":"string","description":"Read-only durable avatar resource id used as the face-swap identity source. Requests use `avatar_handle`."},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"description":"Backward-compatible job lifecycle status. Prefer `resource_status` for resource readiness and `job_status` for job polling state."},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"],"description":"Resource-facing avatar face-swap state. Completed jobs map to `ready`; queued/processing jobs map to `processing`."},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true,"description":"Underlying Sume job lifecycle status, or null if no linked job is available."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"video_url":{"type":"string","format":"uri","nullable":true},"artifacts":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicArtifact"}},"result":{"type":"object","nullable":true,"additionalProperties":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Public-safe beta avatar face-swap resource. Provider task ids, transcripts, prompts, internal workflow state, signed URLs, and raw provider payloads are not part of this contract."},"AvatarFaceSwapSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","avatar_face_swap_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits","job","avatar_face_swap","sync"],"properties":{"request_id":{"type":"string"},"avatar_face_swap_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"avatar_face_swap":{"$ref":"#/components/schemas/PublicAvatarFaceSwap"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"VideoCaptionCreateRequest":{"type":"object","additionalProperties":false,"properties":{"video_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS source video URL. Required unless source_caption_id is supplied, which reuses the earlier caption's source video. Localhost, private-network, non-HTTPS, signed/private URLs, provider task URLs, raw transcripts, renderer fields, browser/runtime fields, and temp paths are not part of this public contract."},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"],"description":"Public caption visual treatment, and a starting point rather than a fixed template — `design` edits any of its colours, type, emphasis, placement and motion. Omitted, the style follows the wording: `slam` for Latin, `black-outline` (white fill, thick black outline) for Korean — and a defaulted style renders without that style's gold spoken-word tint, since a look the caller did not name should not introduce an accent colour. Name the style, or set `design.colors.active`, to get one. Style names only; renderer and provider implementation details remain internal. `korean-ad` is CapCut-style Hangul karaoke for Korean speech (one short phrase at a time, lower-third, the spoken word shifts to a heavy weight) — not movie-style subtitles. `weight-shift`, `black-outline`, `highlight`, `pill-karaoke`, `clip-wipe` and `editorial-emphasis` are Hangul-safe phrase-card identities for Korean talking-head video. `editorial-emphasis` is the two-face one: the card's lead words sit small and left-aligned and the phrase-final eojeol drops to a second line at roughly twice the size in a display face. Korean speech requires one of them: `slam`, `punch` and `tiktok-green` use Latin display faces that render Hangul as tofu, so Hangul `script_text` or `words` sent to those is rejected with `caption_hangul_text_latin_style` rather than silently re-styled."},"font":{"type":"string","enum":["pretendard","do-hyeon","black-han-sans","jua","dunggeunmo","bagel-fat-one","dongle","gasoek-one","yeon-sung","single-day","hi-melody","nanum-pen","gowun-dodum","gmarket-sans","noto-sans-kr","noto-serif-kr","ibm-plex-sans-kr","gothic-a1","hahmlet","song-myung","poor-story","gamja-flower","stylish","sunflower","nanum-gothic","nanum-myeongjo","gaegu","cute-font","east-sea-dokdo"],"description":"Optional Hangul face for the chosen style. Omit to keep that style's own default face (korean-ad, weight-shift and editorial-emphasis use Pretendard; black-outline and clip-wipe use Do Hyeon). Only accepted alongside a Hangul style — korean-ad, weight-shift, black-outline, highlight, pill-karaoke, clip-wipe or editorial-emphasis — because these are Hangul faces and slam/punch/tiktok-green are authored around Latin display faces. Feel: pretendard clean baseline, do-hyeon thick rounded, black-han-sans impact, jua soft rounded, dunggeunmo pixel/retro, bagel-fat-one fat rounded, dongle playful rounded display, gasoek-one ultra-thick impact, yeon-sung brushy, single-day soft handwritten, hi-melody soft rounded cute, nanum-pen handwritten, gowun-dodum soft editorial, gmarket-sans geometric retail display (CapCut/YouTube title staple), noto-sans-kr / noto-serif-kr / ibm-plex-sans-kr / gothic-a1 / nanum-gothic / nanum-myeongjo workhorse families, hahmlet / song-myung / sunflower / stylish / poor-story / gamja-flower / gaegu / cute-font / east-sea-dokdo display and script. Naming a face outside this list is rejected rather than substituted."},"design":{"type":"object","additionalProperties":false,"description":"Optional per-request design overrides merged over the chosen style: colours, typography, placement, phrasing and motion. Not supported on `punch` or `tiktok-green`.","properties":{"colors":{"type":"object","additionalProperties":false,"properties":{"base":{"type":"string","pattern":"^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*(,\\s*(0|1|0?\\.\\d+)\\s*)?\\)|transparent|none|currentcolor)$","description":"Resting glyph colour. Hex, rgb()/rgba(), or transparent. Colours are drawn into the render document, so other CSS syntax is rejected rather than interpolated."},"active":{"type":"string","pattern":"^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*(,\\s*(0|1|0?\\.\\d+)\\s*)?\\)|transparent|none|currentcolor)$","description":"Colour of the token being spoken — the emphasis colour. Hex, rgb()/rgba(), or transparent. Colours are drawn into the render document, so other CSS syntax is rejected rather than interpolated."},"stroke":{"type":"string","pattern":"^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*(,\\s*(0|1|0?\\.\\d+)\\s*)?\\)|transparent|none|currentcolor)$","description":"Outline colour, where the style draws one. Hex, rgb()/rgba(), or transparent. Colours are drawn into the render document, so other CSS syntax is rejected rather than interpolated."},"accent":{"type":"string","pattern":"^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*(,\\s*(0|1|0?\\.\\d+)\\s*)?\\)|transparent|none|currentcolor)$","description":"Highlight block or sweep colour. Hex, rgb()/rgba(), or transparent. Colours are drawn into the render document, so other CSS syntax is rejected rather than interpolated."},"accent_deep":{"type":"string","pattern":"^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*(,\\s*(0|1|0?\\.\\d+)\\s*)?\\)|transparent|none|currentcolor)$","description":"Far end of an accent gradient; defaults to accent. Hex, rgb()/rgba(), or transparent. Colours are drawn into the render document, so other CSS syntax is rejected rather than interpolated."},"card":{"type":"string","pattern":"^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*(,\\s*(0|1|0?\\.\\d+)\\s*)?\\)|transparent|none|currentcolor)$","description":"Card or pill fill. null draws no card. Hex, rgb()/rgba(), or transparent. Colours are drawn into the render document, so other CSS syntax is rejected rather than interpolated.","nullable":true}}},"typography":{"type":"object","additionalProperties":false,"properties":{"base_weight":{"type":"number","minimum":100,"maximum":1000,"description":"Variable font weight of resting text."},"active_weight":{"type":"number","minimum":100,"maximum":1000,"description":"Variable font weight of the spoken token."},"active_scale":{"type":"number","minimum":0.5,"maximum":2,"description":"Scale applied to the spoken token."},"font_size_ratio":{"type":"number","minimum":0.01,"maximum":0.4,"description":"Type size as a fraction of a 1080-wide frame, before the in-browser fit shrinks a long line."},"safe_width_ratio":{"type":"number","minimum":0.3,"maximum":1,"description":"Fraction of frame width a caption line may occupy."},"stroke_width_px":{"type":"number","minimum":0,"maximum":24,"description":"Outline width in pixels at the 1080-wide reference."}}},"placement":{"type":"object","additionalProperties":false,"properties":{"anchor_ratio":{"type":"number","minimum":0.05,"maximum":0.95,"description":"Caption line centre as a fraction of frame height, portrait."},"landscape_anchor_ratio":{"type":"number","minimum":0.05,"maximum":0.95,"description":"Same, for a landscape frame."}}},"phrasing":{"type":"object","additionalProperties":false,"properties":{"max_words":{"type":"number","minimum":1,"maximum":12,"description":"Words per on-screen phrase."},"max_chars":{"type":"number","minimum":4,"maximum":60,"description":"Characters per on-screen phrase."},"pause_seconds":{"type":"number","minimum":0.05,"maximum":3,"description":"Silence that breaks one phrase into the next."}}},"motion":{"type":"object","additionalProperties":false,"properties":{"enter_seconds":{"type":"number","minimum":0,"maximum":2,"description":"Phrase enter duration."},"exit_seconds":{"type":"number","minimum":0,"maximum":2,"description":"Phrase exit duration."},"emphasis_in_seconds":{"type":"number","minimum":0,"maximum":2,"description":"How long the spoken token takes to take the emphasis."},"emphasis_out_seconds":{"type":"number","minimum":0,"maximum":2,"description":"How long it takes to release it."}}}}},"source_caption_id":{"type":"string","pattern":"^vcap_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"Optional. Restyle a completed video caption under a different style. Reuses that caption's source video and its existing word timings, so no second speech-to-text runs. Supply words alongside it only to correct the wording. Billing is unchanged: a restyle is still a render."},"words":{"type":"array","minItems":1,"maxItems":1200,"description":"Optional caller-supplied word timings, in seconds. When present, Sume skips speech-to-text entirely and burns exactly these words at exactly these times. Mutually exclusive with script_text, cues, and segments.","items":{"type":"object","additionalProperties":false,"required":["text","start","end"],"properties":{"text":{"type":"string","minLength":1,"maxLength":200},"start":{"type":"number","minimum":0,"maximum":60},"end":{"type":"number","minimum":0,"maximum":60}}}},"cues":{"type":"array","minItems":1,"maxItems":200,"description":"Optional authored overlay cues (text + start + end seconds). Skips speech-to-text — use this for silent clips or product-card copy the caller already wrote. Phrase-level: each cue is one on-screen span (text may include a newline for a 2-line card). Mutually exclusive with words, segments, and script_text.","items":{"type":"object","additionalProperties":false,"required":["text","start","end"],"properties":{"text":{"type":"string","minLength":1,"maxLength":400},"start":{"type":"number","minimum":0,"maximum":60},"end":{"type":"number","minimum":0,"maximum":60}}}},"segments":{"type":"array","minItems":1,"maxItems":200,"description":"Alias for cues. Authored overlay timings that skip speech-to-text. Mutually exclusive with words, cues, and script_text.","items":{"type":"object","additionalProperties":false,"required":["text","start","end"],"properties":{"text":{"type":"string","minLength":1,"maxLength":400},"start":{"type":"number","minimum":0,"maximum":60},"end":{"type":"number","minimum":0,"maximum":60}}}},"language":{"type":"string","minLength":2,"maxLength":16,"default":"auto","description":"Optional speech-to-text language hint, forwarded to transcription as-is (for example `ko`, `en`). Omit for automatic detection. It never selects the caption style or font: pair Korean speech with a Hangul style explicitly."},"hyperframes_composition":{"type":"object","additionalProperties":false,"required":["html","clips","width","height","duration_seconds"],"description":"Optional compiled HyperFrames composition (clips + GSAP product cards). When present the worker stages local assets and runs `hyperframes render` instead of karaoke overlay or speech-to-captions. duration_seconds is a ceiling of 60, not a required length — the worker probes clips and binds duration to the real source (a 36s master with duration_seconds 60 renders at 36s). The document is rendered byte for byte: a muted <video> with no data-has-audio renders video-only, exactly as the local CLI would, and a document whose bytes change between the caller's check and the render container fails as composition_bytes_rewritten.","properties":{"html":{"type":"string"},"clips":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source_url","relative_path"],"properties":{"id":{"type":"string"},"source_url":{"type":"string","format":"uri"},"relative_path":{"type":"string","pattern":"^(?:assets|fonts)/[A-Za-z0-9._-]+$","description":"The project path the document references — assets/<file> or fonts/<file>. A font, an image or an audio track is a project file like a video; a fonts/<file> entry satisfies an @font-face the kit does not carry."}}}},"width":{"type":"number"},"height":{"type":"number"},"duration_seconds":{"type":"number","description":"Composition length in seconds. Maximum 60 — a ceiling, not a required or default length; up to 1800 where the bake is billed for its run time. The worker probes clips and clamps an overstated value to the real source (60 on a 36s file becomes 36)."},"source_tool":{"type":"string","description":"Which Studio tool submitted this composition (`caption_burn` or `hyperframes_compose`). Additive forensics on the job row; the worker still renders only html + clips."},"html_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"sha256 of `html` as the caller read it back from its check. Forensics only: the worker and the render container report the hash of the document they staged, so a rewrite between the check and Chromium is observable."},"fit_duration_to_media":{"type":"boolean","description":"Clamp the composition to the probed media length on purpose. Off by default: the root data-duration is the length, and a root that declares more time than the staged media has fails as composition_duration_exceeds_media naming the media length (when the worker runs with HYPERFRAMES_NATIVE_DURATION=1; otherwise the legacy clamp still applies)."},"preset":{"type":"object","additionalProperties":false,"required":["slug","source"],"description":"Resolved caption look when `source_tool` is `caption_burn`: built-in slug, workspace `capp_` id, or an inline spec.","properties":{"slug":{"type":"string"},"preset_id":{"type":"string","nullable":true},"source":{"type":"string","enum":["inline_spec","workspace","built_in"]}}},"overrides":{"type":"object","additionalProperties":false,"description":"Knob overrides `caption_burn` applied on top of the resolved preset (stroke, fill, size, shadow, font, position, motion). Omitted keys were not sent.","properties":{"stroke":{"type":"string","nullable":true},"stroke_px":{"type":"number"},"fill":{"type":"string"},"font_size":{"type":"number"},"shadow":{"type":"string","nullable":true},"font":{"type":"string"},"position":{"type":"object","additionalProperties":false,"properties":{"vertical_anchor":{"type":"string","enum":["top","center","bottom"]},"offset_px":{"type":"number"}}},"motion":{"type":"string","enum":["fade","hard-cut"],"description":"`hard-cut` = the caption snaps on/off at its cue window (no fade / scale / slide in, no fade out). Omitted = the preset's fade."}}}}},"script_text":{"type":"string","minLength":1,"maxLength":8000,"description":"Optional predetermined caption copy for speech-aligned burn-in. When provided, Sume keeps speech-to-text word timings as the timing source of truth and aligns burned-in wording to this script via an internal alignment step. Alignment can reject with typed public job errors `script_alignment_mismatch` or `script_alignment_failed` (next_action `simplify_script_text_or_omit`). A silent clip with no speech fails as `caption_no_speech` (next_action `use_overlay_captions`) — pass `cues` / `segments` instead of relying on STT. Mutually exclusive with words, cues, and segments. SRT content, renderer fields, and provider task ids remain unsupported."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Strict Sume video caption request. The public contract accepts a source video URL (or source_caption_id to restyle an earlier caption), public style, optional Hangul font, language hint, optional predetermined script_text, explicit words, or authored cues/segments, and normal job communication options only. Exactly one wording source applies: script_text aligns predetermined copy onto speech-to-text timings; words, cues, or segments supply wording and timings and skip speech-to-text (the silent-clip / overlay path). A speech-to-captions job with no transcript fails as caption_no_speech, not a generic policy reject. Alignment failures surface typed public reasons rather than a generic generation failure. Each accepted job reserves and captures 13 credits for videos up to 60 seconds under the current fixed estimate, restyles included."},"PublicVideoCaption":{"type":"object","required":["id","request_id","status","resource_status","job_status","style","created_at","updated_at","completed_at","video_url","artifacts","result","error"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"],"description":"Public caption style. Renderer and provider implementation details remain internal."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"video_url":{"type":"string","format":"uri","nullable":true},"artifacts":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicArtifact"}},"result":{"type":"object","nullable":true,"additionalProperties":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Public-safe video caption resource. Source URLs, raw transcript words, speech-to-text provider ids, renderer internals, browser/runtime details, signed URLs, and temporary paths are omitted."},"VideoCaptionSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","video_caption_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits","job","video_caption","sync"],"properties":{"request_id":{"type":"string"},"video_caption_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"video_caption":{"$ref":"#/components/schemas/PublicVideoCaption"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"VideoCaptionResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicVideoCaption"}}},"MediaImportCreateRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTPS TikTok or Instagram video/reel URL to import. YouTube and other hosts are rejected with unsupported_platform."},"get_transcript":{"type":"boolean","description":"Optional. When true on TikTok imports, request a provider transcript passthrough when available. Ignored for Instagram."},"source_media_url":{"type":"string","format":"uri","description":"Optional. The post's own video file on its platform's CDN (an HTTPS TikTok or Instagram CDN URL), when the caller already holds it. The import downloads it directly instead of asking the provider for it, and falls back to the provider when it fails or has no sound. Other hosts are rejected with invalid_request."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Strict Sume media import request. Fetches a TikTok/Instagram URL, mirrors bytes into Sume storage (media.sume.com), and records a workspace asset with status mirrored. Fixed estimate 10 credits per accepted import. Practical size cap ~2GB. YouTube is out of v1. Retention policy TODO."},"PublicMediaImport":{"type":"object","required":["id","request_id","status","resource_status","job_status","platform","source_url","created_at","updated_at","completed_at","url","asset_id","media_type","content_type","size_bytes","has_watermark","transcript","source","warnings","result","error"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true},"platform":{"type":"string","enum":["tiktok","instagram"]},"source_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"asset_id":{"type":"string","nullable":true},"media_type":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true},"has_watermark":{"type":"boolean","nullable":true},"transcript":{"type":"string","nullable":true},"source":{"type":"object","nullable":true,"additionalProperties":true},"warnings":{"type":"array","nullable":true,"items":{"type":"string"}},"result":{"type":"object","nullable":true,"additionalProperties":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Public-safe media import resource. TikTok/Instagram URL imports are mirrored into Sume-owned storage (media.sume.com). YouTube is unsupported in v1. Practical size cap ~2GB. Returned URLs are public-by-URL. Retention/expiry is not yet defined. No media_id gate — use url with URL-first generators."},"MediaImportSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","media_import_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits","job","media_import","sync"],"properties":{"request_id":{"type":"string"},"media_import_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"media_import":{"$ref":"#/components/schemas/PublicMediaImport"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"MediaImportResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicMediaImport"}}},"PublicFrame":{"type":"object","required":["t","url","width","height"],"properties":{"t":{"type":"number","minimum":0,"description":"Seconds from the start of the clip or composition."},"url":{"type":"string","format":"uri","nullable":true,"description":"Durable media.sume.com artifact URL for this frame. Null when extraction failed for that one instant; one failed frame does not fail the job."},"width":{"type":"integer","nullable":true,"minimum":1},"height":{"type":"integer","nullable":true,"minimum":1}},"description":"One extracted still."},"VideoFramesCreateRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"properties":{"video_url":{"type":"string","format":"uri","description":"media.sume.com video owned by this workspace. There is no open-internet fetch on this route — import first with media-imports_create."},"at":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"number","minimum":0},"description":"Explicit seconds to capture. Mutually exclusive with fps. Every value must satisfy 0 <= t < duration; the worker answers frame_time_out_of_range with the probed duration otherwise."},"fps":{"type":"number","exclusiveMinimum":0,"maximum":2,"description":"Sampling rate instead of an explicit list. Expanded to mid-bin samples (0.5/fps, 1.5/fps, ...) and capped at 24 frames."},"format":{"type":"string","enum":["jpeg","png"],"default":"jpeg","description":"Frame encoding. png for lossless inspection."},"max_edge":{"type":"integer","minimum":16,"maximum":2160,"description":"Optional long-edge clamp in pixels. Omitted keeps the source frame size."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Frames out of a Sume-hosted video, selected by program. There is no filtergraph, codec, or ffmpeg field on this route: Sume compiles the extract. Fields such as vf, filter, filter_complex, select, ffmpeg, cmd, codec, crf and preset are rejected with ffmpeg_fields_rejected. Source duration cap 300s; 24 frames per call."},"PublicVideoFrames":{"type":"object","required":["id","request_id","status","resource_status","video_url","format","source_duration_seconds","frames","warnings","created_at","updated_at","completed_at","error"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"video_url":{"type":"string","format":"uri"},"format":{"type":"string","enum":["jpeg","png"]},"source_duration_seconds":{"type":"number","nullable":true,"minimum":0},"frames":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicFrame"}},"warnings":{"type":"array","nullable":true,"items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Extracted frames as durable media.sume.com image artifacts. The resource id is the job id — there is no separate resource row to poll."},"VideoFramesSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","video_frames_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","job","video_frames"],"properties":{"request_id":{"type":"string"},"video_frames_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"video_frames":{"$ref":"#/components/schemas/PublicVideoFrames"},"usage":{"type":"object","nullable":true,"additionalProperties":true,"description":"The compute reservation; the job is captured at its own compute, never above it."}}}}},"VideoFramesResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicVideoFrames"}}},"VideoInspectCreateRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"description":"Sume Video inspect 1.0 request. Probes ONE Sume-hosted video (duration, size, rotation, fps, codecs, audio, HDR), samples up to 24 stills as durable media.sume.com image artifacts, and optionally transcribes speech with word timings through Sume STT 1.0. Read-only: it never re-encodes the source and never produces an MP4. Every inspect reserves its compute ceiling and is captured at its own compute, never above the reservation; transcribe true adds the STT 1.0 per-minute rate (omit duration_seconds to reserve one minute). Default mode is sync with a 30-second wait — the response carries the finished inspect when the box answers in time and the queued job otherwise. There is no filtergraph, codec or ffmpeg field on this route: vf / filter / ffmpeg / cmd / codec / crf and friends are rejected with ffmpeg_fields_rejected. Source cap 1800 seconds.","properties":{"video_url":{"type":"string","format":"uri","description":"media.sume.com video (artifact or asset) owned by this workspace. There is no open-internet fetch on this route — import first with media-imports_create."},"frames":{"description":"Still sampling. Omit for 8 mid-bin stills (1 fps when the clip is shorter than 8 s). false for probe only. An object for an explicit program: exactly one of at[] (1-24 seconds) or fps (0 < fps <= 2, mid-bin, capped at 24 frames), plus optional format jpeg|png (default jpeg), max_edge 64-2160 (default 768; pass the source edge for a first-frame restage) and seek precise|fast (default precise).","oneOf":[{"type":"boolean","enum":[false]},{"type":"object","additionalProperties":false,"properties":{"at":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"number","minimum":0}},"fps":{"type":"number","exclusiveMinimum":0,"maximum":2},"format":{"type":"string","enum":["jpeg","png"]},"max_edge":{"type":"integer","minimum":64,"maximum":2160},"seek":{"type":"string","enum":["precise","fast"],"description":"Default precise: decodes to the exact instant. fast snaps each still to the keyframe at or before it — up to one GOP earlier (roughly 0-5 s on typical sources), never later — and skips the decode, which is most of the ffmpeg time on high-bitrate clips. Use fast when skimming a clip; keep precise when the timestamp must match (explicit at[] instants, the default 8-still midpoints). Quality, resolution and the transcript are unchanged; with fast, frames[].sample_times are the instants actually shown and requested_times the ones asked for."}}}]},"transcribe":{"type":"boolean","default":false,"description":"Extract speech with word timings (Sume STT 1.0). Billed at the STT 1.0 per-minute rate on top of the free probe. Check probe.has_audio first; a silent source fails inspect_source_has_no_audio."},"language_code":{"type":"string","minLength":2,"maxLength":16,"description":"Optional STT language hint (for example en or ko). Omit for auto-detect. Only with transcribe."},"segmentation":{"type":"object","additionalProperties":false,"required":["mode"],"description":"Same contract as STT 1.0: mode sentence also returns gapless sentence segments[], which drop straight into caption lines. Only with transcribe.","properties":{"mode":{"type":"string","enum":["sentence"]},"silence_split_seconds":{"type":"number","minimum":0.2,"maximum":3}}},"duration_seconds":{"type":"integer","minimum":1,"maximum":600,"description":"Optional, the clip's length. It does not set the price: Sume reads the clip's length from the file and bills every started minute of the transcript (an unreadable clip is billed the 1800 s source cap). Only with transcribe."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to the provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"PublicVideoInspectProbe":{"type":"object","nullable":true,"required":["duration_seconds","width","height","rotation","fps","container","video_codec","pix_fmt","color_transfer","has_audio","audio_codec","audio_channels","audio_sample_rate","size_bytes","is_still","hdr"],"properties":{"duration_seconds":{"type":"number","nullable":true,"minimum":0},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"rotation":{"type":"number","nullable":true},"fps":{"type":"number","nullable":true},"container":{"type":"string","nullable":true},"video_codec":{"type":"string","nullable":true},"pix_fmt":{"type":"string","nullable":true},"color_transfer":{"type":"string","nullable":true},"has_audio":{"type":"boolean"},"audio_codec":{"type":"string","nullable":true},"audio_channels":{"type":"integer","nullable":true},"audio_sample_rate":{"type":"integer","nullable":true},"size_bytes":{"type":"integer","nullable":true},"is_still":{"type":"boolean"},"hdr":{"type":"boolean","description":"True for PQ / HLG transfers — the sources video_filter refuses (hdr_source_unsupported), surfaced early so a program is never submitted against them."}},"description":"Container facts the worker probed. Read-only."},"PublicVideoInspectTranscript":{"type":"object","nullable":true,"required":["text","language_code","words","segments","audio_url"],"properties":{"text":{"type":"string","nullable":true},"language_code":{"type":"string","nullable":true},"words":{"type":"array","items":{"type":"object","required":["word"],"properties":{"word":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"}}},"description":"Word-level timings, seconds from the start of the video."},"segments":{"type":"array","nullable":true,"items":{"type":"object","required":["index","text","start","end","duration_seconds"],"properties":{"index":{"type":"integer"},"text":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"},"duration_seconds":{"type":"number"}}},"description":"Gapless sentence segments when segmentation.mode sentence was requested; drop straight into caption lines. Null otherwise."},"audio_url":{"type":"string","format":"uri","nullable":true,"description":"The 16 kHz mono pcm_s16le wav the transcript was made from (audio_sample_rate / audio_channels say so), as a durable media.sume.com artifact. It is speech-to-text input — reusable as stt_create audio_url or a voice-clone sample — and NOT a timeline spine: everything above 8 kHz and the stereo image are gone, and a timeline_create render handed it as audio.url warns audio_spine_low_fidelity. For a spine, detach the track with audio_detach (wav at the source rate and channels)."},"audio_sample_rate":{"type":"integer","nullable":true,"description":"Sample rate of audio_url in Hz. Always 16000 today: the speech-to-text rendition, not the source's rate (see probe.audio_sample_rate)."},"audio_channels":{"type":"integer","nullable":true,"description":"Channel count of audio_url. Always 1 today (downmixed for speech-to-text; see probe.audio_channels for the source)."},"audio_duration_seconds":{"type":"number","nullable":true,"description":"Length of audio_url itself in seconds, read from the wav. Can trail probe.duration_seconds by the decoder's priming; trust this one when cutting on it."}}},"PublicVideoInspect":{"type":"object","required":["id","request_id","status","resource_status","video_url","transcribe","probe","frames","transcript","warnings","created_at","updated_at","completed_at","error"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"video_url":{"type":"string","format":"uri"},"transcribe":{"type":"boolean"},"probe":{"$ref":"#/components/schemas/PublicVideoInspectProbe"},"frames":{"type":"array","nullable":true,"items":{"type":"object","required":["t","url","width","height"],"properties":{"t":{"type":"number","minimum":0,"description":"Seconds from the start of the clip or composition."},"url":{"type":"string","format":"uri","nullable":true,"description":"Durable media.sume.com artifact URL for this frame. Null when extraction failed for that one instant; one failed frame does not fail the job."},"width":{"type":"integer","nullable":true,"minimum":1},"height":{"type":"integer","nullable":true,"minimum":1},"sample_times":{"type":"array","items":{"type":"number"},"description":"The instant each tile shows, row-major. Equal to the requested instants with seek precise; the keyframe instants (at or before the request) with seek fast."},"columns":{"type":"integer","minimum":1},"rows":{"type":"integer","minimum":1},"tile_width":{"type":"integer","nullable":true},"tile_height":{"type":"integer","nullable":true},"seek":{"type":"string","enum":["precise","fast"],"description":"Present on seek fast grids: how the stills were seeked."},"requested_times":{"type":"array","items":{"type":"number"},"description":"Present on seek fast grids: the instants the program asked for, row-major, beside the keyframe instants in sample_times."}},"description":"Contact sheet of up to eight samples in row-major order. t is the first sample; tile dimensions preserve sampled resolution. Legacy results may be individual stills."}},"transcript":{"$ref":"#/components/schemas/PublicVideoInspectTranscript"},"warnings":{"type":"array","nullable":true,"items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"A video inspect: probe facts, sampled stills as durable media.sume.com image artifacts, and the optional transcript. The resource id is the job id — there is no separate resource row to poll."},"VideoInspectSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","video_inspect_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","job","video_inspect"],"properties":{"request_id":{"type":"string"},"video_inspect_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"video_inspect":{"$ref":"#/components/schemas/PublicVideoInspect"},"usage":{"type":"object","nullable":true,"additionalProperties":true,"description":"The reservation: the inspect's compute ceiling, plus the STT 1.0 minutes when transcribe was true. Captured at the job's own compute (and the minutes transcribed), never above it."}}}}},"VideoInspectResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicVideoInspect"}}},"ReferenceIngestCreateRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"description":"Sume Reference ingest 1.0 request. Runs the deterministic preflight of ONE Sume-hosted reference clip (≤300 s): shots with frame-exact cuts and one source-resolution keyframe each, source-resolution OCR merged into text tracks, loudness / speech / beat facts, one labeled overview strip and native crops for low-confidence text — into a ReferenceVideoManifest the agent reads once. Read-only: never re-encodes the source, never produces an MP4. A reference_remix read transcribes its speech by default: speech.allow_billed_stt omitted counts as true for purpose reference_remix and false for every other purpose, and an explicit false opts out. Every read reserves its compute ceiling and is captured at its own compute, never above the reservation; a transcribing read adds the STT 1.0 per-minute rate (settled to zero when the track is silent or has no speech). Default mode is sync with a 30-second wait. There is no filtergraph, codec or ffmpeg field on this route: vf / filter / ffmpeg / cmd / codec / crf and friends are rejected with ffmpeg_fields_rejected.","properties":{"video_url":{"type":"string","format":"uri","description":"media.sume.com video (artifact, asset or chat attachment) owned by this workspace. There is no open-internet fetch on this route — import first with media-imports_create."},"purpose":{"type":"string","enum":["reference_remix","brief_format","face_swap","qa"],"description":"What the manifest is for; stored with the job, does not change the analysis. Default reference_remix."},"ocr":{"type":"object","additionalProperties":false,"description":"Source-resolution OCR program. languages ko|en (default both; the recogniser is PP-OCRv5 Korean, which also reads Latin text and digits), fps 0.5–2 for the text-state sampling (default 1; OCR runs on deduplicated states, never on every frame), min_confidence_attach_crop 0–1 (default 0.85): a line under it is flagged needs_verification and its native crop is returned.","properties":{"languages":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","enum":["ko","en"]}},"fps":{"type":"number","minimum":0.5,"maximum":2},"min_confidence_attach_crop":{"type":"number","minimum":0,"maximum":1}}},"speech":{"type":"object","additionalProperties":false,"description":"allow_billed_stt true lets the worker transcribe with Sume STT 1.0 — only when the track is not silent and voice activity detection finds speech; it reserves the STT per-minute rate on submit. Omitted, it defaults to true for purpose reference_remix and false otherwise; pass false to skip. language_code is the STT hint (only when the read transcribes).","properties":{"allow_billed_stt":{"type":"boolean"},"language_code":{"type":"string","minLength":2,"maxLength":16}}},"semantic":{"type":"boolean","default":false,"description":"Reserved for the semantic enrichment pass; true is refused with reference_ingest_semantic_unavailable until it ships."},"delivery":{"type":"object","additionalProperties":false,"description":"How the agent host attaches pixels: inline_strip (default true) ships the overview strip as an image block; inline_crops none | low_confidence_only (default) | all picks which text crops ride along (at most 4).","properties":{"inline_strip":{"type":"boolean","default":true},"inline_crops":{"type":"string","enum":["none","low_confidence_only","all"]}}},"duration_seconds":{"type":"integer","minimum":1,"maximum":300,"description":"Optional, the clip's length. It does not set the price: Sume reads the clip's length from the file and bills every started minute of speech (an unreadable clip is billed the 300 s source cap). Only when the read transcribes."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional caller metadata stored with the Sume job request. It is not sent to any provider."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"ReferenceVideoManifest":{"type":"object","nullable":true,"additionalProperties":true,"required":["schema","source","shots","text_tracks","audio","overview","coverage","uncertain","provenance"],"description":"ReferenceVideoManifest v1 (schema sume.reference_video_manifest/1). Times are seconds on the source clock (3 dp); boxes are normalised [x0, y0, x1, y1] in 0–1 of the rotated frame. source{url, sha256, duration_seconds, width, height, rotation, display_aspect, fps, frame_count, vfr, video_codec, has_audio_track, size_bytes}; shots[{id, start, end, duration, cut_in, cut_out{type hard|gradual|end, confidence, method}, keyframe{t, url, width, height}, palette[{hex, share}], luma_mean, contrast, motion{class, magnitude, method}, text_track_ids[]}] tile [0, duration] with no gap; boundaries[{at, score}] are visual change candidates at 12 samples a second, 32×32 RGB mean absolute difference ≥ 0.1 — mechanical evidence, not editorial shots; text_tracks[{id, text, lang, confidence, start, end, persistence static|animated, bbox, text_height_px, lines, hits, role_hint, card_id, crop_url, crop_attached, needs_verification}] are deduplicated across frames and never corrected; audio{has_track, silent, integrated_lufs, true_peak_dbfs, speech{present, method, language, segments[], words[]}, music{present, tempo_bpm, beat_times[], confidence}}; overview{strip_url, width, height, tiles[{shot_id, t, x, y, w, h, label}]}; coverage{frames_decoded, frames_ocr, ocr_fps, ocr_on_cut_frames, whole_duration}; uncertain[{kind, ref, at, suggested}] names the only reasons to look again; provenance{analyzers, timings_ms, cache_hit}.","properties":{"schema":{"type":"string"},"source":{"type":"object","additionalProperties":true},"shots":{"type":"array","items":{"type":"object","additionalProperties":true}},"boundaries":{"type":"array","items":{"type":"object","required":["at","score"],"properties":{"at":{"type":"number"},"score":{"type":"number"}}}},"text_tracks":{"type":"array","items":{"type":"object","additionalProperties":true}},"audio":{"type":"object","additionalProperties":true},"overview":{"type":"object","additionalProperties":true},"coverage":{"type":"object","additionalProperties":true},"uncertain":{"type":"array","items":{"type":"object","additionalProperties":true}},"provenance":{"type":"object","additionalProperties":true}}},"PublicReferenceIngest":{"type":"object","required":["id","request_id","status","resource_status","video_url","purpose","allow_billed_stt","manifest","warnings","created_at","updated_at","completed_at","error"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"video_url":{"type":"string","format":"uri"},"purpose":{"type":"string"},"allow_billed_stt":{"type":"boolean"},"manifest":{"$ref":"#/components/schemas/ReferenceVideoManifest"},"warnings":{"type":"array","nullable":true,"items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"A reference ingest: the ReferenceVideoManifest once ready (null while processing or failed), with every keyframe, crop and the overview strip as durable media.sume.com image artifacts. The resource id is the job id — there is no separate resource row to poll."},"ReferenceIngestSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","reference_ingest_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","job","reference_ingest"],"properties":{"request_id":{"type":"string"},"reference_ingest_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"reference_ingest":{"$ref":"#/components/schemas/PublicReferenceIngest"},"usage":{"type":"object","nullable":true,"additionalProperties":true,"description":"The reservation: the ingest's compute ceiling, plus the STT 1.0 minutes when the read transcribes (speech.allow_billed_stt true, or omitted for purpose reference_remix). Captured at the job's own compute (and the minutes transcribed), never above it."}}}}},"ReferenceIngestResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicReferenceIngest"}}},"HyperframesPreviewCreateRequest":{"type":"object","additionalProperties":false,"required":["hyperframes_composition"],"properties":{"hyperframes_composition":{"type":"object","additionalProperties":false,"required":["html","clips","width","height","duration_seconds"],"properties":{"html":{"type":"string","minLength":32},"clips":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","additionalProperties":false,"required":["id","source_url","relative_path"],"properties":{"id":{"type":"string","minLength":1,"maxLength":64},"source_url":{"type":"string","format":"uri"},"relative_path":{"type":"string","pattern":"^(?:assets|fonts)/[A-Za-z0-9._-]+$"}}}},"width":{"type":"integer","minimum":16,"maximum":4096},"height":{"type":"integer","minimum":16,"maximum":4096},"duration_seconds":{"type":"number","exclusiveMinimum":0,"maximum":1800,"description":"At most 60 for stills. Where the full-span check is enabled, a `check` request may run up to 1800 so the vendor check covers the whole program."},"source_tool":{"type":"string","minLength":1,"maxLength":64},"html_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"fit_duration_to_media":{"type":"boolean"}},"description":"The same composition document a bake would render — identical clips, dimensions and duration — so a preview cannot show something the render would not."},"at":{"type":"array","minItems":1,"maxItems":6,"items":{"type":"number","minimum":0},"description":"Seconds to capture. Omitted samples 10%, 50% and 97% of the clamped duration, the last one held inside the timeline rather than on the frame after it."},"check":{"type":"object","additionalProperties":false,"properties":{"at":{"type":"array","minItems":1,"maxItems":66,"items":{"type":"number","minimum":0},"description":"At most 6. Where the full-span check is enabled, up to 66: the caption holds sent beside the midpoint grid, since the CLI's `--at` replaces its grid."},"samples":{"type":"integer","minimum":1,"maximum":60},"caption_zone":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[0-9a-zA-Z.,;=%:-]+$"},"snapshots":{"type":"boolean"},"strict":{"type":"boolean"}},"description":"Run the vendor `hyperframes check` in Chromium instead of taking stills: runtime errors, layout overflow / overlap / occlusion, WCAG contrast, `*.motion.json` assertions and — with `caption_zone` (`x0=0;y0=.82;x1=1;y1=1;severity=error`) — caption-band collisions. The job completes with a report even when the check finds errors (the CLI's exit 1 is findings, not a failure); `snapshots` (default true) adds overview frames and per-finding crops; `strict` makes warnings fail the report too."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Preview stills for a HyperFrames composition. One Chromium boot and N screenshots on the caption image — no frame loop, no encode, no MP4."},"PublicHyperframesPreview":{"type":"object","required":["id","request_id","status","resource_status","frames","duration_seconds","engine_version","created_at","updated_at","completed_at","error","check"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"frames":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicFrame"}},"check":{"type":"object","nullable":true,"additionalProperties":true,"required":["ok","findings","images"],"properties":{"ok":{"type":"boolean"},"strict":{"type":"boolean"},"errors":{"type":"integer","minimum":0},"warnings":{"type":"integer","minimum":0},"findings":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["section","severity","code","message"],"properties":{"section":{"type":"string"},"severity":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"selector":{"type":"string"},"fixHint":{"type":"string"},"time":{"type":"number"}}}},"images":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["kind","t","url","filename"],"properties":{"kind":{"type":"string","enum":["overview","finding"]},"t":{"type":"number","nullable":true},"url":{"type":"string","format":"uri"},"filename":{"type":"string"}}}},"report":{"type":"object","additionalProperties":true}},"description":"Present when the job ran the vendor `hyperframes check`: the CLI's verdict and findings with their own severities, overview / finding PNGs stamped stage preview, and the raw report. Null for a stills preview."},"duration_seconds":{"type":"number","nullable":true,"minimum":0},"engine_version":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Composition preview stills as durable media.sume.com PNG artifacts, stamped stage preview — pictures of a composition that has not been rendered, not a deliverable."},"HyperframesPreviewSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","hyperframes_preview_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","job","hyperframes_preview"],"properties":{"request_id":{"type":"string"},"hyperframes_preview_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"hyperframes_preview":{"$ref":"#/components/schemas/PublicHyperframesPreview"},"usage":{"type":"object","nullable":true,"additionalProperties":true,"description":"The compute reservation; the preview is captured at its own compute, never above it."}}}}},"HyperframesPreviewResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicHyperframesPreview"}}},"VideoAnalysisCreateRequest":{"type":"object","additionalProperties":false,"required":["video_url"],"properties":{"video_url":{"type":"string","format":"uri","description":"Public HTTPS video URL to analyze scene-by-scene. Prefer a media.sume.com URL from media-imports_create or a completed Sume generation artifact. YouTube URLs are rejected with unsupported_source."},"max_scenes":{"type":"integer","minimum":2,"maximum":40,"default":24,"description":"Upper bound on returned scenes. Detector may return fewer. Default 24."},"include_transcript":{"type":"boolean","default":false,"description":"When true, attach per-scene speech text and a whole-video transcript when audio is available. v1 may return audio:null until STT wiring is enabled."},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Strict Sume video analysis request. URL-first only — no media_id gate. Fixed estimate 19 credits per accepted analysis for videos ≤120s. Hard duration cap 300s at worker probe. Longer videos are less accurate; short clips give the most reliable results."},"VideoAnalysisScene":{"type":"object","required":["index","start_seconds","end_seconds","duration_seconds","summary","visual","shot_type","camera_motion","on_screen_text","audio","keyframe_url","confidence"],"properties":{"index":{"type":"integer","minimum":0},"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0},"duration_seconds":{"type":"number","minimum":0},"summary":{"type":"string","maxLength":400},"visual":{"type":"string","maxLength":1200},"shot_type":{"type":"string","nullable":true,"enum":["extreme_close_up","close_up","medium","wide","establishing","product_insert","text_card","screen_recording","other",null]},"camera_motion":{"type":"string","nullable":true,"enum":["static","handheld_static","pan","tilt","push_in","pull_out","tracking","whip","other",null]},"on_screen_text":{"type":"array","items":{"type":"string"}},"audio":{"type":"object","nullable":true,"required":["speech","has_speech","has_music"],"properties":{"speech":{"type":"string","nullable":true},"has_speech":{"type":"boolean"},"has_music":{"type":"boolean"}}},"keyframe_url":{"type":"string","format":"uri","nullable":true},"keyframes":{"type":"array","description":"Dense JPEG stills for this scene — at least one per whole second (mid-second ticks, clamped inside the scene). `t` is seconds from video start. `url` is null when that second's extract or mirror failed (`keyframe_mirror_failed:scene_N:t_T`); one failed second does not drop the scene. Hard video duration cap 300s is the stills ceiling. Absent on analyses stored before this field shipped (GET then returns []).","items":{"type":"object","required":["t","url"],"properties":{"t":{"type":"number","minimum":0},"url":{"type":"string","format":"uri","nullable":true}}}},"confidence":{"type":"number","minimum":0,"maximum":1,"nullable":true}},"description":"Concrete scene-by-scene analysis item. TwelveLabs supplies timings and scene text; ffmpeg extracts ≥1 JPEG/sec (`keyframes`) plus a representative `keyframe_url` (the 1s sample nearest 40% of the scene, or the 40% pick on sub-1s scenes)."},"PublicVideoAnalysis":{"type":"object","required":["id","request_id","status","resource_status","job_status","video_url","analysis_version","video","summary","scene_count","scenes","warnings","created_at","updated_at","completed_at","error"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"]},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true},"video_url":{"type":"string","format":"uri"},"analysis_version":{"type":"string","nullable":true},"video":{"type":"object","nullable":true,"additionalProperties":true,"description":"Whole-video probe metadata (duration_seconds, width, height, fps, has_audio) when analysis has completed."},"summary":{"type":"string","nullable":true},"scene_count":{"type":"integer","nullable":true,"minimum":0},"scenes":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/VideoAnalysisScene"}},"warnings":{"type":"array","nullable":true,"items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Public-safe video analysis resource. Scene timings and descriptions come from TwelveLabs video understanding; ffmpeg extracts ≥1 JPEG/sec per scene (`keyframes`) plus a representative `keyframe_url`. Longer videos are less accurate — short clips give the most reliable results. Hard duration cap 300s (also the stills ceiling); soft cap 90s attaches low_confidence_long_video. YouTube URLs are rejected at submit. Keyframe URLs are public-by-URL on media.sume.com."},"VideoAnalysisSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","video_analysis_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits","job","video_analysis","sync"],"properties":{"request_id":{"type":"string"},"video_analysis_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"video_analysis":{"$ref":"#/components/schemas/PublicVideoAnalysis"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"VideoAnalysisResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicVideoAnalysis"}}},"VideoAnalysisListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["video_analyses"],"properties":{"video_analyses":{"type":"array","items":{"$ref":"#/components/schemas/PublicVideoAnalysis"}}}}}},"SumeMediaFile":{"type":"object","description":"A media file in an Action run's structured output. Sume-hosted media is served from media.sume.com with `public, max-age=31536000, immutable` and does not expire. Custom output schemas may reference this shape with `\"$ref\": \"SumeMediaFile#\"`.","required":["type","url","content_type","file_name","size_bytes","width","height","duration_ms","expires_at"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["image","video","audio","file"]},"url":{"type":"string","format":"uri"},"content_type":{"type":["string","null"]},"file_name":{"type":["string","null"]},"size_bytes":{"type":["integer","null"],"minimum":0},"width":{"type":["integer","null"],"minimum":0},"height":{"type":["integer","null"],"minimum":0},"duration_ms":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"],"format":"date-time","description":"null for durable media.sume.com URLs. Populated only when a signed URL is returned."}}},"ActionRunDefaultOutput":{"type":"object","description":"`sume/action-run-output/v1` — the built-in output schema used when an Action binds none. Filled deterministically from the run's generated media and final assistant text; no model call.","required":["text","images","videos","audio","files"],"additionalProperties":false,"properties":{"text":{"type":["string","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/SumeMediaFile"}},"videos":{"type":"array","items":{"$ref":"#/components/schemas/SumeMediaFile"}},"audio":{"type":"array","items":{"$ref":"#/components/schemas/SumeMediaFile"}},"files":{"type":"array","items":{"$ref":"#/components/schemas/SumeMediaFile"}}}},"ActionRunOutputSchemaBinding":{"type":"object","description":"Which output schema produced this receipt's `output`.","required":["name","strict","source"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Schema name, e.g. \"sume/action-run-output/v1\" or a user-defined name."},"strict":{"type":"boolean"},"source":{"type":"string","enum":["default","action_default","request_override"]},"filled_by":{"type":"string","enum":["agent","projection"],"description":"Which path produced `output`. `agent`: the run submitted it during the turn, against your schema. `projection`: the post-run structuring pass built it from the run's media and closing text. Absent when `output` is null, and absent for the built-in default schema, which is filled deterministically by neither path."}}},"ActionRunOutputSchemaRequest":{"type":"object","description":"Per-request output schema override. The schema must satisfy the OpenAI strict-mode subset: object root, `additionalProperties: false` on every object, every property listed in `required` (optionality via nullable unions), <=10 nesting levels, <=5000 properties, and `$ref` limited to `#/$defs/*` and `SumeMediaFile#`. A schema outside the subset is rejected with `400 output_schema_invalid` and `details.violations[]`. `strict: false` is stored but does not relax the subset.","required":["name","schema"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9._/-]+$"},"strict":{"type":"boolean","default":true},"schema":{"type":"object","additionalProperties":true}}},"ActionRunResponseFormatAlias":{"type":"object","description":"Documented OpenAI-shaped alias for `output_schema`. Normalized into `output_schema` on receipt; sending both is a `400 invalid_request`.","required":["type","json_schema"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["json_schema"]},"json_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"}}},"ActionRunOutputError":{"type":"object","description":"Set when a schema-valid `output` could not be produced. On an unattended run — `api` or `cron` — that is a run failure: `status` is `failed` and `error` carries the same reason, because a `completed` receipt with a null `output` reads as a success it is not. `artifacts` is still populated either way. The exception is `output_extraction_failed`, which records a transport failure rather than a verdict and stays `completed`.","required":["code","message","details"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"`agent_reported_failure`: the run's own accepted `return_format_output` said it did not deliver — an explicit-fail payload, media slots reporting `failed` / `stand-in`, or a primary that is not the Format's declared deliverable; `output` carries the ledger of what was made and the run is `failed`. `output_schema_unsatisfied`: the projection did not match the bound schema, or referenced a media URL this run did not produce. `output_extraction_failed`: the projection could not run; `status` stays `completed`, and a `details.reason` of `harvest_unavailable` means the run's media could not be read while it finalized, so the receipt fills in on the next read. `unattended_blocked`: an unattended run stopped rather than claim a deliverable it did not produce; `message` is the reason, `status` is `failed`, and `details.assembled_deliverable: false` marks any harvested media as intermediates rather than the finished cut. `deliverable_missing`: the Format produces media (`io.output_kind`) this run never made, so no structured output was allowed to claim it; `status` is `failed`. `primary_output_missing`: the run satisfied its schema but left the `primary_output_key` you declared without a value, so the result it did produce is on `output` while `status` is `failed` — a partial is never promoted to a success. `provider_unavailable`: the model's provider stream was cut and reconnects ran out before the run produced its deliverable; `status` is `failed`, `details.retryable` is `true`, and the same request is worth re-firing. Treat this set as open — new codes may appear, so do not exhaustively switch on it."},"message":{"type":"string"},"details":{"type":["object","null"],"additionalProperties":true}}},"PublicAction":{"type":"object","description":"An Action (saved Agent instructions plus triggers). The `instructions` text is deliberately omitted.","required":["id","object","title","status","trigger_type","api_trigger_enabled","cron","model","output_schema","primary_output_key","last_run_at","created_at","updated_at","invoke_url","slug","handle","vanity_invoke_url"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["action"]},"title":{"type":"string"},"slug":{"type":["null","string"],"description":"URL segment for the vanity invoke path, unique within the owner. Null on Actions created before slugs existed."},"handle":{"type":["null","string"],"description":"Owner's current account handle, when one is resolvable."},"status":{"type":"string","enum":["active","inactive"]},"trigger_type":{"type":"string","enum":["cron","api"]},"api_trigger_enabled":{"type":"boolean"},"cron":{"type":["null","object"],"required":["expr","timezone","next_run_at"],"properties":{"expr":{"type":"string"},"timezone":{"type":"string"},"next_run_at":{"type":["null","string"],"format":"date-time"}}},"model":{"type":"string"},"output_schema":{"type":["null","object"],"required":["name","strict"],"description":"Action-default output schema binding, or null for the built-in default.","properties":{"name":{"type":"string"},"strict":{"type":"boolean"}}},"primary_output_key":{"type":["null","string"]},"generation_spend_cap_credits":{"type":["null","integer"],"minimum":0,"description":"The Action's own generation cap in credits, or null for the platform default."},"last_run_at":{"type":["null","string"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"invoke_url":{"type":"string","format":"uri","description":"Opaque invoke path. Permanent — store this one; it survives handle and slug renames."},"vanity_invoke_url":{"type":["null","string"],"format":"uri","description":"Human-readable invoke path built from `handle` and `slug`, or null when either is unknown. Convenience only — renaming either changes the URL, so persist `invoke_url` instead."}}},"PublicActionRun":{"type":"object","description":"One execution of an Action, with its schema-constrained `output` and keyless `artifacts` sibling.","required":["id","object","action","status","trigger","created_at","started_at","finished_at","output_schema","output","output_error","primary_output_key","primary_output_url","artifacts","usage","error","skip_reason","request_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","webhook_delivery","idempotency_hit"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["action.run"]},"action":{"type":"object","required":["id","title","trigger_type"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"trigger_type":{"type":"string","enum":["cron","api"]}}},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled","skipped"]},"trigger":{"type":"object","required":["source","idempotency_key"],"properties":{"source":{"type":"string","enum":["cron","manual","api"]},"idempotency_key":{"type":["null","string"]}}},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["null","string"],"format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaBinding"},"output":{"type":["null","object"],"additionalProperties":true,"description":"Schema-constrained result. Null for every non-terminal status, and null whenever the run produced nothing that satisfies `output_schema` — not merely because the run failed. A `failed` run publishes whatever partial result it did author, so a show that rendered 20 of 40 scenes reports those 20 here with the rest marked failed by your own schema. `primary_output_url` stays null on a failure, so the presence of `output` never means the deliverable exists. Shaped by `output_schema`; see `ActionRunDefaultOutput` for the built-in schema."},"output_error":{"oneOf":[{"$ref":"#/components/schemas/ActionRunOutputError"},{"type":"null"}]},"primary_output_key":{"type":["null","string"]},"primary_output_url":{"type":["null","string"],"format":"uri"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicArtifact"}},"usage":{"type":["null","object"],"properties":{"debited_credits":{"type":["null","integer"],"minimum":0,"description":"What the wallet deducted for this run and its thread: captured ledger rows of every operation type, the turn's own LLM row included. Null when the ledger could not say."},"held_credits":{"type":["null","integer"],"minimum":0,"description":"Holds still open (reserved rows, parked pending_* rows included). Not spend."},"refunded_credits":{"type":["null","integer"],"minimum":0,"description":"Holds given back (refunded rows). Not spend."},"debited_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`debited_credits` in whole US cents, rounded up."},"held_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`held_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"final":{"type":["null","boolean"],"description":"True once no hold is open: `debited_credits` will not move."},"cap":{"type":["null","object"],"description":"The run's generation cap: its ceiling (null when the run has no automation ceiling — wallet balance, generation admission and org limits still apply), what counts against it today (reserved + captured generation rows attributed to the run, the agent's own LLM class excluded — not the run's total, which is `debited_credits`), and what is left.","properties":{"limit_credits":{"type":["null","integer"],"minimum":0},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":["null","integer"],"minimum":0},"limit_usd_cents":{"type":["null","integer"],"minimum":0},"counted_usd_cents":{"type":"integer","minimum":0},"remaining_usd_cents":{"type":["null","integer"],"minimum":0}}}}},"error":{"type":["null","object"],"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"skip_reason":{"type":["null","string"]},"request_id":{"type":"string"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Upper bound on this run's wall clock, or null once it is terminal. A run that wedges is force-finalized past a hard ceiling (90 minutes by default) regardless of activity, so this is a real deadline rather than a hint — but it is an upper bound: a run with no activity finalizes sooner, once it is both older than 25 minutes and idle for 10."},"queue":{"type":"object","required":["state","reason","position","retry_after_seconds"],"properties":{"state":{"type":"string","enum":["waiting","runtime_unavailable","processing","done"],"description":"`waiting` while the run is queued and pickup is still within the normal window; `runtime_unavailable` once it has been queued past that window and nothing has claimed it; `processing` once the runtime started it; `done` on any terminal run."},"reason":{"type":"string","enum":["awaiting_runtime","runtime_not_picking_up","runtime_started","terminal"],"description":"`runtime_not_picking_up` says nothing claimed this run — not why. Sume does not know why from here, and guessing would be worse than saying so."},"position":{"type":["null","integer"],"description":"Always `null`. Queue depth is not published: it cannot be computed honestly across both dispatch paths, and a wrong position is worse than none. Declared so a client can branch on it rather than discover its absence later."},"retry_after_seconds":{"type":["null","integer"],"description":"Seconds to wait before polling again. Non-null only while `state` is `runtime_unavailable`."}}},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"events_url":{"type":["null","string"],"format":"uri","description":"Always `null`. Run lifecycle events are not exposed over the API; use `status_url` and `result_url`."},"cancel_url":{"type":"string","format":"uri"},"cancelable":{"type":"boolean"},"next_action":{"type":"string","enum":["poll_status","inspect_events","fix_input","retry_later","contact_support","none"],"description":"What to do next with this run. Run surfaces emit exactly three of these values: `poll_status` while `queued`/`processing`, `retry_later` for a `skipped` run, and `none` for every terminal run — including a failure, where the whole answer is already on this receipt under `error` and `output_error`. The other three are retained in this enum for wire compatibility only and are never returned on a run receipt: `fix_input` and `contact_support` belong to the generation-job surface, and `inspect_events` was retired before the Format phase timeline existed and has stayed retired — a terminal receipt already carries the answer, and while a run is in flight `poll_status` is the instruction, with `events_url` there for detail rather than as a next step."},"webhook_delivery":{"$ref":"#/components/schemas/RunWebhookDelivery"},"idempotency_hit":{"type":"boolean"}}},"ActionResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicAction"}}},"ActionListResponse":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAction"}},"has_more":{"type":"boolean","description":"True when more rows exist past this page. Fetch them by passing `next_cursor` back as `cursor`."},"next_cursor":{"type":["null","string"],"description":"Opaque cursor for the next page, or null on the last page. Pass it back verbatim as `cursor`; do not parse or construct one."}}},"ActionRunResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicActionRun"}}},"ActionRunListResponse":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicActionRun"}},"has_more":{"type":"boolean","description":"True when more rows exist past this page. Fetch them by passing `next_cursor` back as `cursor`."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page, or null on the last page. Pass it back verbatim as `cursor`; do not parse or construct one."}}},"PublicFormat":{"type":"object","description":"A Format (a reusable authoring recipe). The `SKILL.md` body is deliberately omitted — it is injected server-side into each run instruction.","required":["id","object","slug","title","description","source","version","status","api_trigger_enabled","model","created_at","updated_at","invoke_url","handle","vanity_invoke_url"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["format"]},"slug":{"type":"string"},"handle":{"type":["null","string"],"description":"Account handle this Format is addressable at: the owning workspace's handle for a team Format, the owner's own for a personal one. Null when no handle is resolvable, and always null for first-party Formats, which have no owner."},"vanity_invoke_url":{"type":["null","string"],"format":"uri","description":"Human-readable invoke path built from `handle` and `slug`, or null when the handle is unknown or the Format is first-party. Convenience only — renaming either half changes the URL, so persist `invoke_url` instead."},"package_sha":{"type":["null","string"],"description":"Content identity of the published package — the git tree sha, the same value a Contents write reports as `commit.tree.sha`. Send it as `If-Match` on `PUT …/contents` to refuse a commit if the package moved since you read it. Null on a Format published before package shas existed; those are never backfilled and ignore `If-Match`."},"contents_url":{"type":["null","string"],"format":"uri","description":"Package Contents root for this Format: `GET`/`PUT` it to read and commit the files behind it. Null exactly when `vanity_invoke_url` is — the Contents API is addressed by `{handle}/{slug}` only."},"title":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","enum":["first_party","custom"]},"version":{"type":"integer","minimum":1},"status":{"type":"string","enum":["active","inactive"],"description":"`inactive` until the API-call trigger has been provisioned. An inactive Format rejects API runs."},"api_trigger_enabled":{"type":"boolean"},"model":{"type":["null","string"]},"generation_spend_cap_credits":{"type":["null","integer"],"minimum":0,"description":"Most a run of this Format may spend on generation, in credits. Always set in practice: a Format that never named a cap reports the platform default (25,000). A run's own `generation_spend_cap_credits` names its own ceiling, up to the platform maximum of 31,250 — pass `null` to run at that maximum."},"io":{"type":["null","object"],"description":"Declared IO shape from the Format's registration profile. The run body's `input` is a free-form object by design, so this is the only declared contract between a Format's author and its callers — use it to tell a video Format from a text one, and to know what kind of `input` it expects. Null means the Format predates registration, not that it takes no input.","required":["profile","input_kind","output_kind"],"properties":{"profile":{"type":"string","description":"Registration profile. Live values are `url_to_video` and `generic`; `avatar_create` and `live_commerce` are reserved and not yet accepted."},"input_kind":{"type":["null","string"],"description":"What the Format consumes: `url`, `text`, `image`, or `product`. Null when the profile declares none."},"output_kind":{"type":["null","string"],"description":"What the Format produces: `video`, `image`, or `text`. Null when the profile declares none."}}},"showcase":{"type":["null","object"],"description":"A worked example this Format actually produced, captured by the mock run at registration and verified against the generated-media ledger before it was stored. Null when the Format has never produced one.","required":["kind","media_url","thumbnail_url","created_at"],"properties":{"kind":{"type":"string","enum":["image","video"]},"media_url":{"type":"string","format":"uri"},"thumbnail_url":{"type":["null","string"],"format":"uri"},"created_at":{"type":"string","format":"date-time"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"invoke_url":{"type":"string","format":"uri"}}},"PublicFormatRun":{"type":"object","description":"One execution of a Format — one agent turn. Identical to `PublicActionRun` except the owner block is `format`, `thread_id` / `previous_run_id` are added, and the run URLs are `/v1/format-runs/...`.","required":["id","object","status","trigger","created_at","started_at","finished_at","output_schema","output","output_error","primary_output_key","primary_output_url","artifacts","usage","error","skip_reason","request_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","webhook_delivery","idempotency_hit","format"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["format.run"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled","skipped"]},"trigger":{"type":"object","required":["source","idempotency_key"],"properties":{"source":{"type":"string","enum":["cron","manual","api"]},"idempotency_key":{"type":["null","string"]}}},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["null","string"],"format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaBinding"},"output":{"type":["null","object"],"additionalProperties":true,"description":"Schema-constrained result. Null for every non-terminal status, and null whenever the run produced nothing that satisfies `output_schema` — not merely because the run failed. A `failed` run publishes whatever partial result it did author, so a show that rendered 20 of 40 scenes reports those 20 here with the rest marked failed by your own schema. `primary_output_url` stays null on a failure, so the presence of `output` never means the deliverable exists. Shaped by `output_schema`; see `ActionRunDefaultOutput` for the built-in schema."},"output_error":{"oneOf":[{"$ref":"#/components/schemas/ActionRunOutputError"},{"type":"null"}]},"primary_output_key":{"type":["null","string"]},"primary_output_url":{"type":["null","string"],"format":"uri"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicArtifact"}},"usage":{"type":["null","object"],"properties":{"debited_credits":{"type":["null","integer"],"minimum":0,"description":"What the wallet deducted for this run and its thread: captured ledger rows of every operation type, the turn's own LLM row included. Null when the ledger could not say."},"held_credits":{"type":["null","integer"],"minimum":0,"description":"Holds still open (reserved rows, parked pending_* rows included). Not spend."},"refunded_credits":{"type":["null","integer"],"minimum":0,"description":"Holds given back (refunded rows). Not spend."},"debited_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`debited_credits` in whole US cents, rounded up."},"held_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`held_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"final":{"type":["null","boolean"],"description":"True once no hold is open: `debited_credits` will not move."},"cap":{"type":["null","object"],"description":"The run's generation cap: its ceiling (null when the run has no automation ceiling — wallet balance, generation admission and org limits still apply), what counts against it today (reserved + captured generation rows attributed to the run, the agent's own LLM class excluded — not the run's total, which is `debited_credits`), and what is left.","properties":{"limit_credits":{"type":["null","integer"],"minimum":0},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":["null","integer"],"minimum":0},"limit_usd_cents":{"type":["null","integer"],"minimum":0},"counted_usd_cents":{"type":"integer","minimum":0},"remaining_usd_cents":{"type":["null","integer"],"minimum":0}}}}},"error":{"type":["null","object"],"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"skip_reason":{"type":["null","string"]},"request_id":{"type":"string"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Upper bound on this run's wall clock, or null once it is terminal. A run that wedges is force-finalized past a hard ceiling (90 minutes by default) regardless of activity, so this is a real deadline rather than a hint — but it is an upper bound: a run with no activity finalizes sooner, once it is both older than 25 minutes and idle for 10."},"queue":{"type":"object","required":["state","reason","position","retry_after_seconds"],"properties":{"state":{"type":"string","enum":["waiting","runtime_unavailable","processing","done"],"description":"`waiting` while the run is queued and pickup is still within the normal window; `runtime_unavailable` once it has been queued past that window and nothing has claimed it; `processing` once the runtime started it; `done` on any terminal run."},"reason":{"type":"string","enum":["awaiting_runtime","runtime_not_picking_up","runtime_started","terminal"],"description":"`runtime_not_picking_up` says nothing claimed this run — not why. Sume does not know why from here, and guessing would be worse than saying so."},"position":{"type":["null","integer"],"description":"Always `null`. Queue depth is not published: it cannot be computed honestly across both dispatch paths, and a wrong position is worse than none. Declared so a client can branch on it rather than discover its absence later."},"retry_after_seconds":{"type":["null","integer"],"description":"Seconds to wait before polling again. Non-null only while `state` is `runtime_unavailable`."}}},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri","description":"Phase timeline for this run: `GET /v1/format-runs/{run_id}/events`. Tells you which phase the run is in and since when, which `status` alone cannot. Not a log stream — agent output, tool calls and sandbox internals are never published."},"cancel_url":{"type":"string","format":"uri"},"cancelable":{"type":"boolean"},"next_action":{"type":"string","enum":["poll_status","inspect_events","fix_input","retry_later","contact_support","none"],"description":"What to do next with this run. Run surfaces emit exactly three of these values: `poll_status` while `queued`/`processing`, `retry_later` for a `skipped` run, and `none` for every terminal run — including a failure, where the whole answer is already on this receipt under `error` and `output_error`. The other three are retained in this enum for wire compatibility only and are never returned on a run receipt: `fix_input` and `contact_support` belong to the generation-job surface, and `inspect_events` was retired before the Format phase timeline existed and has stayed retired — a terminal receipt already carries the answer, and while a run is in flight `poll_status` is the instruction, with `events_url` there for detail rather than as a next step."},"webhook_delivery":{"$ref":"#/components/schemas/RunWebhookDelivery"},"idempotency_hit":{"type":"boolean"},"format":{"type":"object","required":["id","slug","title","version"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"version":{"type":"integer","minimum":1}}},"model":{"type":"string","description":"Normalized requested orchestrator selection: omitted/empty is `gpt-6.1-sol`; retired `gpt-5.6-sol` is `gpt-6-sol`; explicit Auto is `auto`. This is not the actual served model. Image/video/audio selection is separate."},"requested_model":{"type":"string"},"served_model":{"type":["null","string"],"description":"Last observed runtime model; null until execution telemetry is available. Earlier models remain in model_attempts."},"fallback_used":{"type":"boolean"},"fallback_reason":{"type":["null","string"]},"routing_policy_version":{"type":["null","string"]},"model_attempts":{"type":"array","description":"Ordered recovery attempts, up to the latest 100. Each step has at most three total attempts; successful continuation starts another step. Usage is observed, never estimated.","items":{"type":"object","properties":{"step":{"type":"integer"},"attempt":{"type":"integer","minimum":1,"maximum":3},"model":{"type":"string"},"outcome":{"type":"string","enum":["started","failed","succeeded"]},"reason":{"type":["null","string"]},"usage":{"type":["null","object"],"additionalProperties":{"type":"number"}}}}},"thread_id":{"type":["null","string"],"description":"Agent thread this run's turn happened in. Runs that continue one another share a thread, so two runs with the same `thread_id` are two turns of one conversation. Read-only: continue by sending `previous_run_id`, never by sending a thread id back. Null on a run that never started (an overlap `skipped`)."},"previous_run_id":{"type":["null","string"],"description":"The run this one continued, echoed from the request so continuity is provable rather than inferred. Null on a run that started a fresh conversation."}}},"FormatResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicFormat"}}},"FormatListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicFormat"}},"has_more":{"type":"boolean","description":"True when more rows exist past this page. Fetch them by passing `next_cursor` back as `cursor`."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page, or null on the last page. Pass it back verbatim as `cursor`; do not parse or construct one."}}},"PublicSkill":{"type":"object","description":"One first-party Sume skill: a package of `SKILL.md` plus optional `references/` that an agent reads and follows. `atomic` skills are workflows and capability playbooks; `format` skills are the runnable presets also listed under `/v1/formats` as `sume/{slug}`.","additionalProperties":false,"required":["object","slug","title","description","layer","package_sha","files"],"properties":{"object":{"type":"string","enum":["skill"]},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"layer":{"type":"string","enum":["atomic","format"]},"package_sha":{"type":"string","description":"Git tree sha of the package version this environment serves."},"files":{"type":"integer","minimum":0}}},"SkillListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicSkill"}}}},"PublicWorkspace":{"type":"object","description":"One workspace the signed-in person can work in: their personal workspace or a team they belong to.","additionalProperties":false,"required":["object","id","name","kind","is_selected"],"properties":{"object":{"type":"string","enum":["workspace"]},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["personal","team"]},"is_selected":{"type":"boolean","description":"True for the workspace this connection works in now: its balance pays for generations and its assets and jobs are read."}}},"WorkspaceListResponse":{"type":"object","required":["object","data","selected_workspace_id","switchable"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicWorkspace"}},"selected_workspace_id":{"type":"string"},"switchable":{"type":"boolean","description":"True for a Sume sign-in (MCP connection or `sume login`), which can switch with `POST /v1/workspaces/select`. An API key belongs to one workspace."}}},"WorkspaceSelectionResponse":{"type":"object","required":["object","workspace","previous_workspace_id"],"properties":{"object":{"type":"string","enum":["workspace_selection"]},"workspace":{"$ref":"#/components/schemas/PublicWorkspace"},"previous_workspace_id":{"type":"string"}}},"PublicFormatGrant":{"type":"object","additionalProperties":false,"required":["id","object","format","grantee_workspace_id","grantee_workspace_handle","role","status","created_at","accepted_at","revoked_at"],"properties":{"id":{"type":"string","description":"Opaque grant id (`fgr_…`) — the accept call's address."},"object":{"type":"string","enum":["format.grant"]},"format":{"type":["null","object"],"additionalProperties":false,"required":["id","slug","title","handle"],"description":"The shared Format's card. Null only when the Format was archived after the invite went out.","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"handle":{"type":["null","string"],"description":"The owner workspace's addressing handle. A grant never re-homes the Format: the grantee lists, reads and invokes it at this handle, unchanged."}}},"grantee_workspace_id":{"type":"string","description":"Clerk org id of the workspace the Format is shared with."},"grantee_workspace_handle":{"type":["null","string"],"description":"Display handle for the grantee workspace, when resolved."},"role":{"type":"string","enum":["run","write"],"description":"What the grant allows, always billed to the grantee workspace. `run` is list + read + invoke + overlay. `write` is that plus editing the package through the Contents API at the owner's same `{handle}/{slug}`. Managing the roster itself is never granted — invite, re-role and revoke stay with the owning workspace."},"status":{"type":"string","enum":["pending","accepted"],"description":"`pending` confers nothing — the grantee workspace's admin must accept before the Format resolves for it."},"created_at":{"type":"string","format":"date-time"},"accepted_at":{"type":["null","string"],"format":"date-time"},"revoked_at":{"type":["null","string"],"format":"date-time","description":"Set on the receipt a revoke returns; live rosters never list revoked grants."}}},"FormatGrantResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicFormatGrant"}}},"FormatGrantListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicFormatGrant"}}}},"FormatGrantCreateRequest":{"type":"object","additionalProperties":false,"required":["workspace"],"properties":{"workspace":{"type":"string","minLength":2,"maxLength":39,"description":"The invited workspace, as its team handle (e.g. `kiwi`). User handles are not grantable — sharing is workspace-to-workspace."},"role":{"type":"string","enum":["run","write"],"default":"run","description":"What to grant. Omit for `run` — a client that predates this field never starts granting `write` by accident."}}},"FormatGrantUpdateRequest":{"type":"object","additionalProperties":false,"required":["role"],"properties":{"role":{"type":"string","enum":["run","write"],"description":"The role to move this grant to. Required — an omitted role would read as a silent downgrade to `run`."}}},"FormatRunResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicFormatRun"}}},"PublicFormatRunQueueCounts":{"type":"object","additionalProperties":false,"required":["total","queued","running","completed","failed","canceled"],"properties":{"total":{"type":"integer","minimum":0},"queued":{"type":"integer","minimum":0},"running":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"canceled":{"type":"integer","minimum":0}}},"PublicFormatRunQueueItem":{"type":"object","additionalProperties":false,"required":["index","status","run_id","error"],"properties":{"index":{"type":"integer","minimum":0,"description":"Zero-based position in the submitted `items` array."},"status":{"type":"string","enum":["queued","running","completed","failed","canceled"],"description":"`queued` has not started yet (`run_id` is null). `running` is inside the concurrency window. `completed` / `failed` / `canceled` are terminal and free a slot for the next queued item."},"run_id":{"type":["null","string"],"description":"Child Format run id once this item has been dispatched. Null while queued. Poll `GET /v1/format-runs/{run_id}` for the full receipt."},"error":{"type":["null","object"],"additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"PublicFormatRunQueue":{"type":"object","additionalProperties":false,"description":"One bulk Format-run queue. The server keeps `concurrency` child runs in flight and starts the next queued item as soon as any in-flight run completes or fails.","required":["id","object","format","concurrency","status","counts","items","created_at","updated_at","finished_at","status_url"],"properties":{"id":{"type":"string","description":"Queue id (`frq_…`)."},"object":{"type":"string","enum":["format.run_queue"]},"format":{"type":"object","additionalProperties":false,"required":["id","slug","title","version"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"version":{"type":"integer","minimum":1}}},"concurrency":{"type":"integer","minimum":1,"maximum":16,"description":"How many child Format runs stay in flight at once. When one hits `completed` or `failed`, the next queued item starts immediately."},"status":{"type":"string","enum":["queued","running","completed"],"description":"`queued` means nothing has dispatched yet. `running` means the concurrency window is draining the list. `completed` means every item is terminal — inspect `counts` for failures."},"counts":{"$ref":"#/components/schemas/PublicFormatRunQueueCounts"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicFormatRunQueueItem"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for progress: `GET /v1/format-run-queues/{id}`."}}},"FormatRunQueueResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicFormatRunQueue"}}},"FormatRunCancelResponse":{"type":"object","required":["data","cancel_effect"],"properties":{"data":{"$ref":"#/components/schemas/PublicFormatRun"},"cancel_effect":{"type":"string","enum":["canceled","no_op"],"description":"`canceled` — this call stopped a run that was still in flight. `no_op` — the run had already reached a terminal status and nothing changed. A canceled run never delivers a webhook, so `canceled` also means no callback is coming."}}},"FormatRunListResponse":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicFormatRun"}},"has_more":{"type":"boolean","description":"True when more rows exist past this page. Fetch them by passing `next_cursor` back as `cursor`."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page, or null on the last page. Pass it back verbatim as `cursor`; do not parse or construct one."}}},"PublicAgentRun":{"type":"object","description":"One Agent Completion run — an unattended Studio Agent turn with tools, media generation, and sandbox. Identical to `PublicActionRun` except there is no saved owner object (so no `action` block), `model` and `thread_id` are added, and the run URLs are `/v1/agent-runs/...`.","required":["id","object","status","trigger","created_at","started_at","finished_at","output_schema","output","output_error","primary_output_key","primary_output_url","artifacts","usage","error","skip_reason","request_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","webhook_delivery","idempotency_hit","model","thread_id"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["agent.run"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled","skipped"]},"trigger":{"type":"object","required":["source","idempotency_key"],"properties":{"source":{"type":"string","enum":["cron","manual","api"]},"idempotency_key":{"type":["null","string"]}}},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["null","string"],"format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaBinding"},"output":{"type":["null","object"],"additionalProperties":true,"description":"Schema-constrained result. Null for every non-terminal status, and null whenever the run produced nothing that satisfies `output_schema` — not merely because the run failed. A `failed` run publishes whatever partial result it did author, so a show that rendered 20 of 40 scenes reports those 20 here with the rest marked failed by your own schema. `primary_output_url` stays null on a failure, so the presence of `output` never means the deliverable exists. Shaped by `output_schema`; see `ActionRunDefaultOutput` for the built-in schema."},"output_error":{"oneOf":[{"$ref":"#/components/schemas/ActionRunOutputError"},{"type":"null"}]},"primary_output_key":{"type":["null","string"]},"primary_output_url":{"type":["null","string"],"format":"uri"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicArtifact"}},"usage":{"type":["null","object"],"properties":{"debited_credits":{"type":["null","integer"],"minimum":0,"description":"What the wallet deducted for this run and its thread: captured ledger rows of every operation type, the turn's own LLM row included. Null when the ledger could not say."},"held_credits":{"type":["null","integer"],"minimum":0,"description":"Holds still open (reserved rows, parked pending_* rows included). Not spend."},"refunded_credits":{"type":["null","integer"],"minimum":0,"description":"Holds given back (refunded rows). Not spend."},"debited_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`debited_credits` in whole US cents, rounded up."},"held_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`held_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"final":{"type":["null","boolean"],"description":"True once no hold is open: `debited_credits` will not move."},"cap":{"type":["null","object"],"description":"The run's generation cap: its ceiling (null when the run has no automation ceiling — wallet balance, generation admission and org limits still apply), what counts against it today (reserved + captured generation rows attributed to the run, the agent's own LLM class excluded — not the run's total, which is `debited_credits`), and what is left.","properties":{"limit_credits":{"type":["null","integer"],"minimum":0},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":["null","integer"],"minimum":0},"limit_usd_cents":{"type":["null","integer"],"minimum":0},"counted_usd_cents":{"type":"integer","minimum":0},"remaining_usd_cents":{"type":["null","integer"],"minimum":0}}}}},"error":{"type":["null","object"],"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"skip_reason":{"type":["null","string"]},"request_id":{"type":"string"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Upper bound on this run's wall clock, or null once it is terminal. A run that wedges is force-finalized past a hard ceiling (90 minutes by default) regardless of activity, so this is a real deadline rather than a hint — but it is an upper bound: a run with no activity finalizes sooner, once it is both older than 25 minutes and idle for 10."},"queue":{"type":"object","required":["state","reason","position","retry_after_seconds"],"properties":{"state":{"type":"string","enum":["waiting","runtime_unavailable","processing","done"],"description":"`waiting` while the run is queued and pickup is still within the normal window; `runtime_unavailable` once it has been queued past that window and nothing has claimed it; `processing` once the runtime started it; `done` on any terminal run."},"reason":{"type":"string","enum":["awaiting_runtime","runtime_not_picking_up","runtime_started","terminal"],"description":"`runtime_not_picking_up` says nothing claimed this run — not why. Sume does not know why from here, and guessing would be worse than saying so."},"position":{"type":["null","integer"],"description":"Always `null`. Queue depth is not published: it cannot be computed honestly across both dispatch paths, and a wrong position is worse than none. Declared so a client can branch on it rather than discover its absence later."},"retry_after_seconds":{"type":["null","integer"],"description":"Seconds to wait before polling again. Non-null only while `state` is `runtime_unavailable`."}}},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"events_url":{"type":["null","string"],"format":"uri","description":"Always `null`. Run lifecycle events are not exposed over the API; use `status_url` and `result_url`."},"cancel_url":{"type":"string","format":"uri"},"cancelable":{"type":"boolean"},"next_action":{"type":"string","enum":["poll_status","inspect_events","fix_input","retry_later","contact_support","none"],"description":"What to do next with this run. Run surfaces emit exactly three of these values: `poll_status` while `queued`/`processing`, `retry_later` for a `skipped` run, and `none` for every terminal run — including a failure, where the whole answer is already on this receipt under `error` and `output_error`. The other three are retained in this enum for wire compatibility only and are never returned on a run receipt: `fix_input` and `contact_support` belong to the generation-job surface, and `inspect_events` was retired before the Format phase timeline existed and has stayed retired — a terminal receipt already carries the answer, and while a run is in flight `poll_status` is the instruction, with `events_url` there for detail rather than as a next step."},"webhook_delivery":{"$ref":"#/components/schemas/RunWebhookDelivery"},"idempotency_hit":{"type":"boolean"},"model":{"type":"string"},"thread_id":{"type":["null","string"],"description":"Studio Agent thread this completion ran in. A new thread per completion in this version."}}},"AgentRunResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicAgentRun"}}},"AgentRunListResponse":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAgentRun"}},"has_more":{"type":"boolean","description":"True when more rows exist past this page. Fetch them by passing `next_cursor` back as `cursor`."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page, or null on the last page. Pass it back verbatim as `cursor`; do not parse or construct one."}}},"ActionRunStatusResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","started_at","finished_at","next_action","cancelable"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled","skipped"]},"started_at":{"type":["null","string"],"format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"next_action":{"type":"string","enum":["poll_status","inspect_events","fix_input","retry_later","contact_support","none"],"description":"What to do next with this run. Run surfaces emit exactly three of these values: `poll_status` while `queued`/`processing`, `retry_later` for a `skipped` run, and `none` for every terminal run — including a failure, where the whole answer is already on this receipt under `error` and `output_error`. The other three are retained in this enum for wire compatibility only and are never returned on a run receipt: `fix_input` and `contact_support` belong to the generation-job surface, and `inspect_events` was retired before the Format phase timeline existed and has stayed retired — a terminal receipt already carries the answer, and while a run is in flight `poll_status` is the instruction, with `events_url` there for detail rather than as a next step."},"cancelable":{"type":"boolean"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Upper bound on this run's wall clock, or null once it is terminal. A run that wedges is force-finalized past a hard ceiling (90 minutes by default) regardless of activity, so this is a real deadline rather than a hint — but it is an upper bound: a run with no activity finalizes sooner, once it is both older than 25 minutes and idle for 10."},"queue":{"type":"object","required":["state","reason","position","retry_after_seconds"],"properties":{"state":{"type":"string","enum":["waiting","runtime_unavailable","processing","done"],"description":"`waiting` while the run is queued and pickup is still within the normal window; `runtime_unavailable` once it has been queued past that window and nothing has claimed it; `processing` once the runtime started it; `done` on any terminal run."},"reason":{"type":"string","enum":["awaiting_runtime","runtime_not_picking_up","runtime_started","terminal"],"description":"`runtime_not_picking_up` says nothing claimed this run — not why. Sume does not know why from here, and guessing would be worse than saying so."},"position":{"type":["null","integer"],"description":"Always `null`. Queue depth is not published: it cannot be computed honestly across both dispatch paths, and a wrong position is worse than none. Declared so a client can branch on it rather than discover its absence later."},"retry_after_seconds":{"type":["null","integer"],"description":"Seconds to wait before polling again. Non-null only while `state` is `runtime_unavailable`."}}},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri","description":"Phase timeline for this run. Present on a Format run, absent on the Action and Agent surfaces, which have no events route behind them."},"cancel_url":{"type":"string","format":"uri"},"error":{"type":["null","object"],"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":["null","object"],"properties":{"debited_credits":{"type":["null","integer"],"minimum":0,"description":"What the wallet deducted for this run and its thread: captured ledger rows of every operation type, the turn's own LLM row included. Null when the ledger could not say."},"held_credits":{"type":["null","integer"],"minimum":0,"description":"Holds still open (reserved rows, parked pending_* rows included). Not spend."},"refunded_credits":{"type":["null","integer"],"minimum":0,"description":"Holds given back (refunded rows). Not spend."},"debited_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`debited_credits` in whole US cents, rounded up."},"held_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`held_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"final":{"type":["null","boolean"],"description":"True once no hold is open: `debited_credits` will not move."},"cap":{"type":["null","object"],"description":"The run's generation cap: its ceiling (null when the run has no automation ceiling — wallet balance, generation admission and org limits still apply), what counts against it today (reserved + captured generation rows attributed to the run, the agent's own LLM class excluded — not the run's total, which is `debited_credits`), and what is left.","properties":{"limit_credits":{"type":["null","integer"],"minimum":0},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":["null","integer"],"minimum":0},"limit_usd_cents":{"type":["null","integer"],"minimum":0},"counted_usd_cents":{"type":"integer","minimum":0},"remaining_usd_cents":{"type":["null","integer"],"minimum":0}}}}}}}}},"FormatRunStatusResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","started_at","finished_at","next_action","cancelable"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled","skipped"]},"started_at":{"type":["null","string"],"format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"next_action":{"type":"string","enum":["poll_status","inspect_events","fix_input","retry_later","contact_support","none"],"description":"What to do next with this run. Run surfaces emit exactly three of these values: `poll_status` while `queued`/`processing`, `retry_later` for a `skipped` run, and `none` for every terminal run — including a failure, where the whole answer is already on this receipt under `error` and `output_error`. The other three are retained in this enum for wire compatibility only and are never returned on a run receipt: `fix_input` and `contact_support` belong to the generation-job surface, and `inspect_events` was retired before the Format phase timeline existed and has stayed retired — a terminal receipt already carries the answer, and while a run is in flight `poll_status` is the instruction, with `events_url` there for detail rather than as a next step."},"cancelable":{"type":"boolean"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Upper bound on this run's wall clock, or null once it is terminal. A run that wedges is force-finalized past a hard ceiling (90 minutes by default) regardless of activity, so this is a real deadline rather than a hint — but it is an upper bound: a run with no activity finalizes sooner, once it is both older than 25 minutes and idle for 10."},"queue":{"type":"object","required":["state","reason","position","retry_after_seconds"],"properties":{"state":{"type":"string","enum":["waiting","runtime_unavailable","processing","done"],"description":"`waiting` while the run is queued and pickup is still within the normal window; `runtime_unavailable` once it has been queued past that window and nothing has claimed it; `processing` once the runtime started it; `done` on any terminal run."},"reason":{"type":"string","enum":["awaiting_runtime","runtime_not_picking_up","runtime_started","terminal"],"description":"`runtime_not_picking_up` says nothing claimed this run — not why. Sume does not know why from here, and guessing would be worse than saying so."},"position":{"type":["null","integer"],"description":"Always `null`. Queue depth is not published: it cannot be computed honestly across both dispatch paths, and a wrong position is worse than none. Declared so a client can branch on it rather than discover its absence later."},"retry_after_seconds":{"type":["null","integer"],"description":"Seconds to wait before polling again. Non-null only while `state` is `runtime_unavailable`."}}},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri","description":"Phase timeline for this run. Present on a Format run, absent on the Action and Agent surfaces, which have no events route behind them."},"cancel_url":{"type":"string","format":"uri"},"error":{"type":["null","object"],"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":["null","object"],"properties":{"debited_credits":{"type":["null","integer"],"minimum":0,"description":"What the wallet deducted for this run and its thread: captured ledger rows of every operation type, the turn's own LLM row included. Null when the ledger could not say."},"held_credits":{"type":["null","integer"],"minimum":0,"description":"Holds still open (reserved rows, parked pending_* rows included). Not spend."},"refunded_credits":{"type":["null","integer"],"minimum":0,"description":"Holds given back (refunded rows). Not spend."},"debited_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`debited_credits` in whole US cents, rounded up."},"held_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`held_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"final":{"type":["null","boolean"],"description":"True once no hold is open: `debited_credits` will not move."},"cap":{"type":["null","object"],"description":"The run's generation cap: its ceiling (null when the run has no automation ceiling — wallet balance, generation admission and org limits still apply), what counts against it today (reserved + captured generation rows attributed to the run, the agent's own LLM class excluded — not the run's total, which is `debited_credits`), and what is left.","properties":{"limit_credits":{"type":["null","integer"],"minimum":0},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":["null","integer"],"minimum":0},"limit_usd_cents":{"type":["null","integer"],"minimum":0},"counted_usd_cents":{"type":"integer","minimum":0},"remaining_usd_cents":{"type":["null","integer"],"minimum":0}}}}}}}}},"FormatRunEventsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Phase entries, oldest first. Consecutive entries reporting the same phase and status are collapsed into one carrying the most recent sighting, so a chatty phase does not flood the array.","items":{"type":"object","required":["at","phase","status","duration_ms"],"properties":{"at":{"type":"string","format":"date-time","description":"When this phase was last seen in this status. Also the run's progress clock: if it stops advancing, the run is stalled rather than slow."},"phase":{"type":"string","enum":["preparing","running","finalizing"],"description":"`preparing` is everything before the agent has the run in hand, `running` is the agent working, `finalizing` is teardown and output harvest."},"status":{"type":"string","enum":["pending","running","done","warning","error","skipped"]},"duration_ms":{"type":["null","integer"],"minimum":0,"description":"How long the phase took, when it measured itself. Null otherwise — not zero."}}}}}},"FormatContentEntry":{"type":"object","description":"One entry in a Format package listing, in GitHub's Contents vocabulary.","additionalProperties":false,"required":["type","name","path","sha","size"],"properties":{"type":{"type":"string","enum":["file","dir"]},"name":{"type":"string"},"path":{"type":"string","description":"Path relative to the package root, e.g. `references/plan.md`."},"sha":{"type":"string","description":"Git blob sha for a file, subtree sha for a directory. A file's sha is the value `PUT`/`DELETE` take as their `sha` precondition."},"size":{"type":"integer","minimum":0,"description":"Stored UTF-8 bytes for a file; 0 for a directory."}}},"FormatContentFile":{"type":"object","description":"One Format package file, base64-encoded like GitHub's.","required":["type","name","path","sha","size","encoding","content"],"properties":{"type":{"type":"string","enum":["file"]},"name":{"type":"string"},"path":{"type":"string","description":"Path relative to the package root, e.g. `references/plan.md`."},"sha":{"type":"string","description":"Git blob sha for a file, subtree sha for a directory. A file's sha is the value `PUT`/`DELETE` take as their `sha` precondition."},"size":{"type":"integer","minimum":0,"description":"Stored UTF-8 bytes for a file; 0 for a directory."},"encoding":{"type":"string","enum":["base64"]},"content":{"type":"string","description":"Base64-encoded UTF-8 file body."}}},"FormatContentsResponse":{"type":"object","required":["data"],"properties":{"data":{"description":"A single file object when the path names a file, or an array of entries when it names a directory or the package root. `GET …/contents?recursive=1` answers with the same array, every row a file object with its body.","oneOf":[{"$ref":"#/components/schemas/FormatContentFile"},{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/FormatContentFile"},{"$ref":"#/components/schemas/FormatContentEntry"}]}}]}}},"FormatContentWriteResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["content","commit","version"],"properties":{"content":{"description":"The file as it now stands, or null after a delete — GitHub's shape.","oneOf":[{"$ref":"#/components/schemas/FormatContentFile"},{"type":"null"}]},"commit":{"type":"object","description":"The commit this write produced on the Format's package history.","required":["sha","message","tree","parents"],"properties":{"sha":{"type":"string"},"message":{"type":"string"},"tree":{"type":"object","required":["sha"],"description":"Root tree of the new package — the same value the catalog stores as `package_sha`, and the value to send back as `If-Match` on the next write.","properties":{"sha":{"type":"string"}}},"parents":{"type":"array","items":{"type":"object","required":["sha"],"properties":{"sha":{"type":"string"}}}}}},"version":{"type":"integer","minimum":1,"description":"Display counter after the write. Not part of GitHub's reply; it is what the dashboard shows next to the Format."}}}}},"FormatContentBatchWriteResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["content","commit","version"],"properties":{"content":{"type":"array","description":"Every file this commit wrote, in the order the request listed them. Files the request did not name are unchanged and are not reported here.","items":{"$ref":"#/components/schemas/FormatContentFile"}},"commit":{"type":"object","description":"The commit this write produced on the Format's package history.","required":["sha","message","tree","parents"],"properties":{"sha":{"type":"string"},"message":{"type":"string"},"tree":{"type":"object","required":["sha"],"description":"Root tree of the new package — the same value the catalog stores as `package_sha`, and the value to send back as `If-Match` on the next write.","properties":{"sha":{"type":"string"}}},"parents":{"type":"array","items":{"type":"object","required":["sha"],"properties":{"sha":{"type":"string"}}}}}},"version":{"type":"integer","minimum":1,"description":"Display counter after the write. Not part of GitHub's reply; it is what the dashboard shows next to the Format."}}}}},"FormatContentPutRequest":{"type":"object","required":["message","content"],"additionalProperties":false,"properties":{"message":{"type":"string","minLength":1,"maxLength":500,"description":"Commit message for this write."},"content":{"type":"string","description":"Base64-encoded UTF-8 file body. The whole file, not a patch — one `PUT` replaces one path."},"sha":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"Git blob sha of the file being replaced, as returned by `GET …/contents/{path}`. Required when the path already exists; omit it to create a new file."}}},"FormatContentBatchPutRequest":{"type":"object","required":["message","files"],"additionalProperties":false,"properties":{"message":{"type":"string","minLength":1,"maxLength":500,"description":"Commit message for this write."},"files":{"type":"array","minItems":1,"maxItems":1000,"description":"Files to write in this one commit. Each path is written whole, as `PUT …/{path}` writes one. Paths the package holds but this list omits are left untouched.","items":{"type":"object","required":["path","content"],"additionalProperties":false,"properties":{"path":{"type":"string","minLength":1,"maxLength":200,"description":"Package-relative path, e.g. `SKILL.md` or `references/plan.md`. Each path may appear once."},"content":{"type":"string","description":"Base64-encoded UTF-8 file body. The whole file, not a patch."},"sha":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"Git blob sha of the file being replaced, as returned by `GET …/contents/{path}`. Required when the path already exists; omit it to create a new file."}}}}}},"FormatContentDeleteRequest":{"type":"object","required":["message","sha"],"additionalProperties":false,"properties":{"message":{"type":"string","minLength":1,"maxLength":500,"description":"Commit message for this write."},"sha":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"Git blob sha of the file being replaced, as returned by `GET …/contents/{path}`. Required when the path already exists; omit it to create a new file."}}},"FormatCreateRequest":{"type":"object","required":["slug"],"additionalProperties":false,"properties":{"slug":{"type":"string","minLength":1,"maxLength":64,"description":"URL name for the Format, unique within your workspace — the `{slug}` half of every `{handle}/{slug}` address it answers at. Lowercase, matching `^[a-z0-9][a-z0-9._-]*$`. `409 skill_slug_taken` if the workspace already has one, `409 skill_slug_reserved` if a Format by Sume holds the name."},"title":{"type":"string","maxLength":80,"description":"Display name shown in the Formats library. Defaults to the slug."},"description":{"type":"string","maxLength":1024,"description":"One line describing what the Format does, written into the seed `SKILL.md` frontmatter — the file stays the single source of truth, and the catalog reads the Format's description back out of it. Single line only; commit a longer one with the Contents API. Defaults to a placeholder."},"auto_init":{"type":"boolean","default":true,"description":"Commit a minimal valid `SKILL.md` so the Format is immediately readable and writable through the Contents API. Only `true` is supported: every Format package must contain `SKILL.md`, so there is no empty Format to create, and `false` is a `400`."}}},"AgentRunStatusResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","started_at","finished_at","next_action","cancelable"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled","skipped"]},"started_at":{"type":["null","string"],"format":"date-time"},"finished_at":{"type":["null","string"],"format":"date-time"},"next_action":{"type":"string","enum":["poll_status","inspect_events","fix_input","retry_later","contact_support","none"],"description":"What to do next with this run. Run surfaces emit exactly three of these values: `poll_status` while `queued`/`processing`, `retry_later` for a `skipped` run, and `none` for every terminal run — including a failure, where the whole answer is already on this receipt under `error` and `output_error`. The other three are retained in this enum for wire compatibility only and are never returned on a run receipt: `fix_input` and `contact_support` belong to the generation-job surface, and `inspect_events` was retired before the Format phase timeline existed and has stayed retired — a terminal receipt already carries the answer, and while a run is in flight `poll_status` is the instruction, with `events_url` there for detail rather than as a next step."},"cancelable":{"type":"boolean"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Upper bound on this run's wall clock, or null once it is terminal. A run that wedges is force-finalized past a hard ceiling (90 minutes by default) regardless of activity, so this is a real deadline rather than a hint — but it is an upper bound: a run with no activity finalizes sooner, once it is both older than 25 minutes and idle for 10."},"queue":{"type":"object","required":["state","reason","position","retry_after_seconds"],"properties":{"state":{"type":"string","enum":["waiting","runtime_unavailable","processing","done"],"description":"`waiting` while the run is queued and pickup is still within the normal window; `runtime_unavailable` once it has been queued past that window and nothing has claimed it; `processing` once the runtime started it; `done` on any terminal run."},"reason":{"type":"string","enum":["awaiting_runtime","runtime_not_picking_up","runtime_started","terminal"],"description":"`runtime_not_picking_up` says nothing claimed this run — not why. Sume does not know why from here, and guessing would be worse than saying so."},"position":{"type":["null","integer"],"description":"Always `null`. Queue depth is not published: it cannot be computed honestly across both dispatch paths, and a wrong position is worse than none. Declared so a client can branch on it rather than discover its absence later."},"retry_after_seconds":{"type":["null","integer"],"description":"Seconds to wait before polling again. Non-null only while `state` is `runtime_unavailable`."}}},"status_url":{"type":"string","format":"uri"},"result_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri","description":"Phase timeline for this run. Present on a Format run, absent on the Action and Agent surfaces, which have no events route behind them."},"cancel_url":{"type":"string","format":"uri"},"error":{"type":["null","object"],"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":["null","object"],"properties":{"debited_credits":{"type":["null","integer"],"minimum":0,"description":"What the wallet deducted for this run and its thread: captured ledger rows of every operation type, the turn's own LLM row included. Null when the ledger could not say."},"held_credits":{"type":["null","integer"],"minimum":0,"description":"Holds still open (reserved rows, parked pending_* rows included). Not spend."},"refunded_credits":{"type":["null","integer"],"minimum":0,"description":"Holds given back (refunded rows). Not spend."},"debited_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`debited_credits` in whole US cents, rounded up."},"held_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`held_credits` in whole US cents, rounded up."},"refunded_usd_cents":{"type":["null","integer"],"minimum":0,"description":"`refunded_credits` in whole US cents, rounded up."},"final":{"type":["null","boolean"],"description":"True once no hold is open: `debited_credits` will not move."},"cap":{"type":["null","object"],"description":"The run's generation cap: its ceiling (null when the run has no automation ceiling — wallet balance, generation admission and org limits still apply), what counts against it today (reserved + captured generation rows attributed to the run, the agent's own LLM class excluded — not the run's total, which is `debited_credits`), and what is left.","properties":{"limit_credits":{"type":["null","integer"],"minimum":0},"counted_credits":{"type":"integer","minimum":0},"remaining_credits":{"type":["null","integer"],"minimum":0},"limit_usd_cents":{"type":["null","integer"],"minimum":0},"counted_usd_cents":{"type":"integer","minimum":0},"remaining_usd_cents":{"type":["null","integer"],"minimum":0}}}}}}}}},"AvatarVideoCreateRequest":{"type":"object","additionalProperties":false,"required":[],"description":"Create one Avatar Video from either a legacy single script or ordered multi-scene video_inputs. Provide exactly one of script or video_inputs. For multi-scene requests, avatar_handle is an optional default when every scene provides its own avatar reference. Optional package runs captions-then-mux soundtrack post-production after the clean talking-head.","properties":{"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."},"script":{"type":"string","minLength":1,"description":"Spoken or acted script for the avatar video. Sume estimates target duration from the script and accepts 4-12 seconds inclusive."},"video_inputs":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["voice"],"properties":{"id":{"type":"string","minLength":1,"maxLength":100,"description":"Optional client-provided stable scene id for metadata."},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."},"character":{"type":"object","additionalProperties":false,"required":["type"],"oneOf":[{"required":["avatar_id"]},{"required":["avatar_handle"]}],"properties":{"type":{"type":"string","enum":["avatar"]},"avatar_id":{"type":"string","minLength":1},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."}},"description":"Optional Creatify-style character reference. Current Avatar Video execution supports one resolved avatar per final video; distinct scene avatars are rejected."},"voice":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"description":"Spoken scene. Provide exactly one of script or input_text (runtime-enforced).","properties":{"type":{"type":"string","enum":["text"]},"script":{"type":"string","minLength":1,"maxLength":2000},"input_text":{"type":"string","minLength":1,"maxLength":2000},"duration":{"type":"number","minimum":0.001,"maximum":12,"description":"Optional requested scene duration in seconds for text scenes."}}},{"type":"object","additionalProperties":false,"required":["type","duration"],"description":"Non-speaking scene. duration is required; script/input_text are not allowed.","properties":{"type":{"type":"string","enum":["silence"]},"duration":{"type":"number","minimum":0.001,"maximum":12,"description":"Required silence duration in seconds (no spoken script)."}}}],"description":"Per-scene voice. Discriminated by type: text (spoken) or silence (non-speaking beat with required duration)."},"background":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["prompt","image"]},"prompt":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","description":"Fetchable public HTTPS image URL. Video backgrounds are not supported in this MVP."},"fit":{"type":"string","enum":["crop","contain","cover"]}},"description":"Optional per-scene background metadata. Current execution requires all provided scene backgrounds to resolve to one shared scene."},"scene":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","prompt"],"properties":{"type":{"type":"string","enum":["prompt"]},"prompt":{"type":"string","minLength":1}}},{"type":"object","additionalProperties":false,"required":["type","image_url"],"properties":{"type":{"type":"string","enum":["photo"]},"image_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS scene image URL. Localhost, private-network, non-HTTPS, and non-image responses are rejected before provider submission."}}}]},"duration_seconds":{"type":"number","minimum":0.001,"maximum":12},"duration":{"type":"number","minimum":0.001,"maximum":12},"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0.001,"maximum":12},"timing":{"type":"object","additionalProperties":false,"properties":{"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0.001,"maximum":12}}}}},"description":"Ordered multi-scene input for one Avatar Video, made as one clip. Provide exactly one of top-level script or video_inputs. Total planned output duration must be 4-12 seconds inclusive. Requests within that duration can still fail with public_reason content_policy_rejected when a provider rejects generated clip content."},"product_image":{"type":"string","format":"uri","description":"Optional fetchable public HTTPS product/reference image URL. When omitted, Sume generates a productless avatar video. Localhost, private-network, non-HTTPS, and non-image responses are rejected before provider submission."},"scene":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","prompt"],"properties":{"type":{"type":"string","enum":["prompt"]},"prompt":{"type":"string","minLength":1}}},{"type":"object","additionalProperties":false,"required":["type","image_url"],"properties":{"type":{"type":"string","enum":["photo"]},"image_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS scene image URL. Localhost, private-network, non-HTTPS, and non-image responses are rejected before provider submission."}}}]},"resolution":{"type":"string","enum":["720p"]},"quality":{"type":"string","enum":["standard","plus","max"],"default":"plus","description":"Avatar Video quality selector. `plus` is the default; `standard` requests the fastest Sume execution path and `max` requests the highest quality tier."},"aspect_ratio":{"type":"string","default":"9:16","description":"Optional avatar-video composition ratio. Supported values: 1:1, 3:4, 9:16, 4:3, 16:9. Default: 9:16. Values outside the supported set are treated as the default for compatibility."},"title":{"type":"string"},"captions":{"type":"object","additionalProperties":false,"required":["enabled"],"description":"Optional inline captions for the final Avatar Video. When enabled, Sume burns captions into the clean final MP4 after generation. By default wording is derived from the avatar script / video_inputs spoken text; optional script_text pins predetermined on-screen copy (same wording/timing contract as standalone POST /v1/video-captions: wording SoT = script_text, timing SoT = STT). Preview stills are never captioned; captions stored on preview create apply only at generate-video. Caption stage failures soft-fail: the avatar job stays successful with the clean primary video and captions.status=failed. When client-provided script_text fails alignment, captions soft-fail with typed public_reason and do not burn STT wording. Estimated duration above 60 seconds is rejected. Does not create a separate billed video_caption job; the fixed caption add-on (13 credits) is included in the avatar-video usage estimate when enabled. Mutually exclusive with package.captions (xor).","properties":{"enabled":{"type":"boolean","description":"When true, run caption burn-in after the clean final avatar video is ready. When false or omitted, behavior matches today's clean-video path with no caption add-on charge."},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"],"default":"slam","description":"Public caption visual treatment. Defaults to slam when enabled. Korean speech needs a Hangul style (korean-ad or one of the phrase-card identities); Hangul copy on slam/punch/tiktok-green is rejected rather than re-styled, because those draw in Latin display faces that render Hangul as tofu."},"font":{"type":"string","enum":["pretendard","do-hyeon","black-han-sans","jua","dunggeunmo","bagel-fat-one","dongle","gasoek-one","yeon-sung","single-day","hi-melody","nanum-pen","gowun-dodum","gmarket-sans","noto-sans-kr","noto-serif-kr","ibm-plex-sans-kr","gothic-a1","hahmlet","song-myung","poor-story","gamja-flower","stylish","sunflower","nanum-gothic","nanum-myeongjo","gaegu","cute-font","east-sea-dokdo"],"description":"Optional Hangul face for the chosen style. Omit to keep that style's own default face (korean-ad, weight-shift and editorial-emphasis use Pretendard; black-outline and clip-wipe use Do Hyeon). Only accepted alongside a Hangul style — korean-ad, weight-shift, black-outline, highlight, pill-karaoke, clip-wipe or editorial-emphasis — because these are Hangul faces and slam/punch/tiktok-green are authored around Latin display faces. Feel: pretendard clean baseline, do-hyeon thick rounded, black-han-sans impact, jua soft rounded, dunggeunmo pixel/retro, bagel-fat-one fat rounded, dongle playful rounded display, gasoek-one ultra-thick impact, yeon-sung brushy, single-day soft handwritten, hi-melody soft rounded cute, nanum-pen handwritten, gowun-dodum soft editorial, gmarket-sans geometric retail display (CapCut/YouTube title staple), noto-sans-kr / noto-serif-kr / ibm-plex-sans-kr / gothic-a1 / nanum-gothic / nanum-myeongjo workhorse families, hahmlet / song-myung / sunflower / stylish / poor-story / gamja-flower / gaegu / cute-font / east-sea-dokdo display and script. Naming a face outside this list is rejected rather than substituted."},"language":{"type":"string","minLength":2,"maxLength":16,"default":"auto","description":"Optional speech-to-text language hint, forwarded to transcription as-is (for example `ko`, `en`). Omit for automatic detection. It never selects the caption style or font: pair Korean speech with a Hangul style explicitly."},"script_text":{"type":"string","minLength":1,"maxLength":8000,"description":"Optional predetermined caption copy. When provided, Sume keeps speech-to-text word timings as the timing source of truth and aligns burned-in wording to this script via an internal alignment step. Alignment failures soft-fail inline captions with typed public_reason `script_alignment_mismatch` or `script_alignment_failed` (no silent STT wording burn); omit script_text to derive copy from the spoken script (derived path may fall back to STT wording on mismatch). Only valid when enabled is true. Raw transcripts, cue lists, SRT content, renderer fields, and provider task ids remain unsupported."}}},"package":{"type":"object","additionalProperties":false,"description":"Optional Avatar Video package post-production. When both captions and soundtrack are set, server order is: clean talking-head → captions on CLEAN → (Music 1.0 from soundtrack.prompt OR use soundtrack.audio_url) → mux BGM under captioned (or clean if captions skipped/soft-failed). Never mux-then-caption with script alignment. Soft-fail: caption or soundtrack/mux failure keeps the furthest successful primary video_url (captioned when ready, else clean). Mutually exclusive with top-level captions when package.captions.enabled is also set (xor).","properties":{"captions":{"type":"object","additionalProperties":false,"required":["enabled"],"description":"Optional inline captions for the final Avatar Video. When enabled, Sume burns captions into the clean final MP4 after generation. By default wording is derived from the avatar script / video_inputs spoken text; optional script_text pins predetermined on-screen copy (same wording/timing contract as standalone POST /v1/video-captions: wording SoT = script_text, timing SoT = STT). Preview stills are never captioned; captions stored on preview create apply only at generate-video. Caption stage failures soft-fail: the avatar job stays successful with the clean primary video and captions.status=failed. When client-provided script_text fails alignment, captions soft-fail with typed public_reason and do not burn STT wording. Estimated duration above 60 seconds is rejected. Does not create a separate billed video_caption job; the fixed caption add-on (13 credits) is included in the avatar-video usage estimate when enabled. Mutually exclusive with package.captions (xor).","properties":{"enabled":{"type":"boolean","description":"When true, run caption burn-in after the clean final avatar video is ready. When false or omitted, behavior matches today's clean-video path with no caption add-on charge."},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"],"default":"slam","description":"Public caption visual treatment. Defaults to slam when enabled. Korean speech needs a Hangul style (korean-ad or one of the phrase-card identities); Hangul copy on slam/punch/tiktok-green is rejected rather than re-styled, because those draw in Latin display faces that render Hangul as tofu."},"font":{"type":"string","enum":["pretendard","do-hyeon","black-han-sans","jua","dunggeunmo","bagel-fat-one","dongle","gasoek-one","yeon-sung","single-day","hi-melody","nanum-pen","gowun-dodum","gmarket-sans","noto-sans-kr","noto-serif-kr","ibm-plex-sans-kr","gothic-a1","hahmlet","song-myung","poor-story","gamja-flower","stylish","sunflower","nanum-gothic","nanum-myeongjo","gaegu","cute-font","east-sea-dokdo"],"description":"Optional Hangul face for the chosen style. Omit to keep that style's own default face (korean-ad, weight-shift and editorial-emphasis use Pretendard; black-outline and clip-wipe use Do Hyeon). Only accepted alongside a Hangul style — korean-ad, weight-shift, black-outline, highlight, pill-karaoke, clip-wipe or editorial-emphasis — because these are Hangul faces and slam/punch/tiktok-green are authored around Latin display faces. Feel: pretendard clean baseline, do-hyeon thick rounded, black-han-sans impact, jua soft rounded, dunggeunmo pixel/retro, bagel-fat-one fat rounded, dongle playful rounded display, gasoek-one ultra-thick impact, yeon-sung brushy, single-day soft handwritten, hi-melody soft rounded cute, nanum-pen handwritten, gowun-dodum soft editorial, gmarket-sans geometric retail display (CapCut/YouTube title staple), noto-sans-kr / noto-serif-kr / ibm-plex-sans-kr / gothic-a1 / nanum-gothic / nanum-myeongjo workhorse families, hahmlet / song-myung / sunflower / stylish / poor-story / gamja-flower / gaegu / cute-font / east-sea-dokdo display and script. Naming a face outside this list is rejected rather than substituted."},"language":{"type":"string","minLength":2,"maxLength":16,"default":"auto","description":"Optional speech-to-text language hint, forwarded to transcription as-is (for example `ko`, `en`). Omit for automatic detection. It never selects the caption style or font: pair Korean speech with a Hangul style explicitly."},"script_text":{"type":"string","minLength":1,"maxLength":8000,"description":"Optional predetermined caption copy. When provided, Sume keeps speech-to-text word timings as the timing source of truth and aligns burned-in wording to this script via an internal alignment step. Alignment failures soft-fail inline captions with typed public_reason `script_alignment_mismatch` or `script_alignment_failed` (no silent STT wording burn); omit script_text to derive copy from the spoken script (derived path may fall back to STT wording on mismatch). Only valid when enabled is true. Raw transcripts, cue lists, SRT content, renderer fields, and provider task ids remain unsupported."}}},"soundtrack":{"type":"object","additionalProperties":false,"description":"Optional soundtrack for Avatar Video package post-production. Exactly one of prompt or audio_url is required (xor; no mode enum). prompt: Music 1.0 generate then ffmpeg mux (Music 1.0 estimate reserved). audio_url: public HTTPS BYO BGM → mirror into Sume media then mux only (no Music reservation; the mux is free). Standalone POST /v1/music-1.0/generate remains unchanged. Create/preview validate URL shape; full accessibility is checked at generate-video (soft-fail if dead).","properties":{"prompt":{"type":"string","minLength":1,"maxLength":5000,"description":"Music 1.0 text prompt used to generate the BGM bed. Mutually exclusive with audio_url."},"audio_url":{"type":"string","format":"uri","description":"Public HTTPS URL of an existing BGM audio file to mux under the talking-head. Mutually exclusive with prompt. Localhost/private URLs are rejected. Prefer a durable public URL; the worker mirrors into Sume media before mux when possible."},"volume":{"type":"number","minimum":0.05,"maximum":0.4,"default":0.15,"description":"Linear BGM volume for mux under speech. Defaults to 0.15 (skill-lab Stage P default)."}}}}},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"AvatarVideoPreviewCreateRequest":{"type":"object","additionalProperties":false,"required":[],"description":"Create only the Avatar Video first-frame preview stage from either a legacy single script or ordered multi-scene video_inputs. Optional captions and package intent are stored on the preview resource and applied only when generate-video runs; preview stills are never caption-burned or muxed. Use the returned preview id with generate-video to start final video generation.","properties":{"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."},"script":{"type":"string","minLength":1,"description":"Spoken or acted script for the avatar video. Sume estimates target duration from the script and accepts 4-12 seconds inclusive."},"video_inputs":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["voice"],"properties":{"id":{"type":"string","minLength":1,"maxLength":100,"description":"Optional client-provided stable scene id for metadata."},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."},"character":{"type":"object","additionalProperties":false,"required":["type"],"oneOf":[{"required":["avatar_id"]},{"required":["avatar_handle"]}],"properties":{"type":{"type":"string","enum":["avatar"]},"avatar_id":{"type":"string","minLength":1},"avatar_handle":{"type":"string","minLength":2,"maxLength":31,"pattern":"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$","description":"Instagram-style avatar handle. Inputs may include a leading @ and are normalized to lowercase without @. Allows letters, digits, underscores, and periods. Hyphens are not supported; periods and underscores cannot be first, last, or consecutive."}},"description":"Optional Creatify-style character reference. Current Avatar Video execution supports one resolved avatar per final video; distinct scene avatars are rejected."},"voice":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"description":"Spoken scene. Provide exactly one of script or input_text (runtime-enforced).","properties":{"type":{"type":"string","enum":["text"]},"script":{"type":"string","minLength":1,"maxLength":2000},"input_text":{"type":"string","minLength":1,"maxLength":2000},"duration":{"type":"number","minimum":0.001,"maximum":12,"description":"Optional requested scene duration in seconds for text scenes."}}},{"type":"object","additionalProperties":false,"required":["type","duration"],"description":"Non-speaking scene. duration is required; script/input_text are not allowed.","properties":{"type":{"type":"string","enum":["silence"]},"duration":{"type":"number","minimum":0.001,"maximum":12,"description":"Required silence duration in seconds (no spoken script)."}}}],"description":"Per-scene voice. Discriminated by type: text (spoken) or silence (non-speaking beat with required duration)."},"background":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["prompt","image"]},"prompt":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","description":"Fetchable public HTTPS image URL. Video backgrounds are not supported in this MVP."},"fit":{"type":"string","enum":["crop","contain","cover"]}},"description":"Optional per-scene background metadata. Current execution requires all provided scene backgrounds to resolve to one shared scene."},"scene":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","prompt"],"properties":{"type":{"type":"string","enum":["prompt"]},"prompt":{"type":"string","minLength":1}}},{"type":"object","additionalProperties":false,"required":["type","image_url"],"properties":{"type":{"type":"string","enum":["photo"]},"image_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS scene image URL. Localhost, private-network, non-HTTPS, and non-image responses are rejected before provider submission."}}}]},"duration_seconds":{"type":"number","minimum":0.001,"maximum":12},"duration":{"type":"number","minimum":0.001,"maximum":12},"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0.001,"maximum":12},"timing":{"type":"object","additionalProperties":false,"properties":{"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0.001,"maximum":12}}}}},"description":"Ordered multi-scene input for one Avatar Video, made as one clip. Provide exactly one of top-level script or video_inputs. Total planned output duration must be 4-12 seconds inclusive. Requests within that duration can still fail with public_reason content_policy_rejected when a provider rejects generated clip content."},"product_image":{"type":"string","format":"uri","description":"Optional fetchable public HTTPS product/reference image URL. When omitted, Sume generates a productless avatar video. Localhost, private-network, non-HTTPS, and non-image responses are rejected before provider submission."},"scene":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","prompt"],"properties":{"type":{"type":"string","enum":["prompt"]},"prompt":{"type":"string","minLength":1}}},{"type":"object","additionalProperties":false,"required":["type","image_url"],"properties":{"type":{"type":"string","enum":["photo"]},"image_url":{"type":"string","format":"uri","description":"Fetchable public HTTPS scene image URL. Localhost, private-network, non-HTTPS, and non-image responses are rejected before provider submission."}}}]},"resolution":{"type":"string","enum":["720p"]},"quality":{"type":"string","enum":["standard","plus","max"],"default":"plus","description":"Avatar Video quality selector. `plus` is the default; `standard` requests the fastest Sume execution path and `max` requests the highest quality tier."},"aspect_ratio":{"type":"string","default":"9:16","description":"Optional avatar-video composition ratio. Supported values: 1:1, 3:4, 9:16, 4:3, 16:9. Default: 9:16. Values outside the supported set are treated as the default for compatibility."},"title":{"type":"string"},"captions":{"type":"object","additionalProperties":false,"required":["enabled"],"description":"Optional inline captions for the final Avatar Video. When enabled, Sume burns captions into the clean final MP4 after generation. By default wording is derived from the avatar script / video_inputs spoken text; optional script_text pins predetermined on-screen copy (same wording/timing contract as standalone POST /v1/video-captions: wording SoT = script_text, timing SoT = STT). Preview stills are never captioned; captions stored on preview create apply only at generate-video. Caption stage failures soft-fail: the avatar job stays successful with the clean primary video and captions.status=failed. When client-provided script_text fails alignment, captions soft-fail with typed public_reason and do not burn STT wording. Estimated duration above 60 seconds is rejected. Does not create a separate billed video_caption job; the fixed caption add-on (13 credits) is included in the avatar-video usage estimate when enabled. Mutually exclusive with package.captions (xor).","properties":{"enabled":{"type":"boolean","description":"When true, run caption burn-in after the clean final avatar video is ready. When false or omitted, behavior matches today's clean-video path with no caption add-on charge."},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"],"default":"slam","description":"Public caption visual treatment. Defaults to slam when enabled. Korean speech needs a Hangul style (korean-ad or one of the phrase-card identities); Hangul copy on slam/punch/tiktok-green is rejected rather than re-styled, because those draw in Latin display faces that render Hangul as tofu."},"font":{"type":"string","enum":["pretendard","do-hyeon","black-han-sans","jua","dunggeunmo","bagel-fat-one","dongle","gasoek-one","yeon-sung","single-day","hi-melody","nanum-pen","gowun-dodum","gmarket-sans","noto-sans-kr","noto-serif-kr","ibm-plex-sans-kr","gothic-a1","hahmlet","song-myung","poor-story","gamja-flower","stylish","sunflower","nanum-gothic","nanum-myeongjo","gaegu","cute-font","east-sea-dokdo"],"description":"Optional Hangul face for the chosen style. Omit to keep that style's own default face (korean-ad, weight-shift and editorial-emphasis use Pretendard; black-outline and clip-wipe use Do Hyeon). Only accepted alongside a Hangul style — korean-ad, weight-shift, black-outline, highlight, pill-karaoke, clip-wipe or editorial-emphasis — because these are Hangul faces and slam/punch/tiktok-green are authored around Latin display faces. Feel: pretendard clean baseline, do-hyeon thick rounded, black-han-sans impact, jua soft rounded, dunggeunmo pixel/retro, bagel-fat-one fat rounded, dongle playful rounded display, gasoek-one ultra-thick impact, yeon-sung brushy, single-day soft handwritten, hi-melody soft rounded cute, nanum-pen handwritten, gowun-dodum soft editorial, gmarket-sans geometric retail display (CapCut/YouTube title staple), noto-sans-kr / noto-serif-kr / ibm-plex-sans-kr / gothic-a1 / nanum-gothic / nanum-myeongjo workhorse families, hahmlet / song-myung / sunflower / stylish / poor-story / gamja-flower / gaegu / cute-font / east-sea-dokdo display and script. Naming a face outside this list is rejected rather than substituted."},"language":{"type":"string","minLength":2,"maxLength":16,"default":"auto","description":"Optional speech-to-text language hint, forwarded to transcription as-is (for example `ko`, `en`). Omit for automatic detection. It never selects the caption style or font: pair Korean speech with a Hangul style explicitly."},"script_text":{"type":"string","minLength":1,"maxLength":8000,"description":"Optional predetermined caption copy. When provided, Sume keeps speech-to-text word timings as the timing source of truth and aligns burned-in wording to this script via an internal alignment step. Alignment failures soft-fail inline captions with typed public_reason `script_alignment_mismatch` or `script_alignment_failed` (no silent STT wording burn); omit script_text to derive copy from the spoken script (derived path may fall back to STT wording on mismatch). Only valid when enabled is true. Raw transcripts, cue lists, SRT content, renderer fields, and provider task ids remain unsupported."}}},"package":{"type":"object","additionalProperties":false,"description":"Optional Avatar Video package post-production. When both captions and soundtrack are set, server order is: clean talking-head → captions on CLEAN → (Music 1.0 from soundtrack.prompt OR use soundtrack.audio_url) → mux BGM under captioned (or clean if captions skipped/soft-failed). Never mux-then-caption with script alignment. Soft-fail: caption or soundtrack/mux failure keeps the furthest successful primary video_url (captioned when ready, else clean). Mutually exclusive with top-level captions when package.captions.enabled is also set (xor).","properties":{"captions":{"type":"object","additionalProperties":false,"required":["enabled"],"description":"Optional inline captions for the final Avatar Video. When enabled, Sume burns captions into the clean final MP4 after generation. By default wording is derived from the avatar script / video_inputs spoken text; optional script_text pins predetermined on-screen copy (same wording/timing contract as standalone POST /v1/video-captions: wording SoT = script_text, timing SoT = STT). Preview stills are never captioned; captions stored on preview create apply only at generate-video. Caption stage failures soft-fail: the avatar job stays successful with the clean primary video and captions.status=failed. When client-provided script_text fails alignment, captions soft-fail with typed public_reason and do not burn STT wording. Estimated duration above 60 seconds is rejected. Does not create a separate billed video_caption job; the fixed caption add-on (13 credits) is included in the avatar-video usage estimate when enabled. Mutually exclusive with package.captions (xor).","properties":{"enabled":{"type":"boolean","description":"When true, run caption burn-in after the clean final avatar video is ready. When false or omitted, behavior matches today's clean-video path with no caption add-on charge."},"style":{"type":"string","enum":["slam","punch","tiktok-green","korean-ad","weight-shift","black-outline","highlight","pill-karaoke","clip-wipe","editorial-emphasis"],"default":"slam","description":"Public caption visual treatment. Defaults to slam when enabled. Korean speech needs a Hangul style (korean-ad or one of the phrase-card identities); Hangul copy on slam/punch/tiktok-green is rejected rather than re-styled, because those draw in Latin display faces that render Hangul as tofu."},"font":{"type":"string","enum":["pretendard","do-hyeon","black-han-sans","jua","dunggeunmo","bagel-fat-one","dongle","gasoek-one","yeon-sung","single-day","hi-melody","nanum-pen","gowun-dodum","gmarket-sans","noto-sans-kr","noto-serif-kr","ibm-plex-sans-kr","gothic-a1","hahmlet","song-myung","poor-story","gamja-flower","stylish","sunflower","nanum-gothic","nanum-myeongjo","gaegu","cute-font","east-sea-dokdo"],"description":"Optional Hangul face for the chosen style. Omit to keep that style's own default face (korean-ad, weight-shift and editorial-emphasis use Pretendard; black-outline and clip-wipe use Do Hyeon). Only accepted alongside a Hangul style — korean-ad, weight-shift, black-outline, highlight, pill-karaoke, clip-wipe or editorial-emphasis — because these are Hangul faces and slam/punch/tiktok-green are authored around Latin display faces. Feel: pretendard clean baseline, do-hyeon thick rounded, black-han-sans impact, jua soft rounded, dunggeunmo pixel/retro, bagel-fat-one fat rounded, dongle playful rounded display, gasoek-one ultra-thick impact, yeon-sung brushy, single-day soft handwritten, hi-melody soft rounded cute, nanum-pen handwritten, gowun-dodum soft editorial, gmarket-sans geometric retail display (CapCut/YouTube title staple), noto-sans-kr / noto-serif-kr / ibm-plex-sans-kr / gothic-a1 / nanum-gothic / nanum-myeongjo workhorse families, hahmlet / song-myung / sunflower / stylish / poor-story / gamja-flower / gaegu / cute-font / east-sea-dokdo display and script. Naming a face outside this list is rejected rather than substituted."},"language":{"type":"string","minLength":2,"maxLength":16,"default":"auto","description":"Optional speech-to-text language hint, forwarded to transcription as-is (for example `ko`, `en`). Omit for automatic detection. It never selects the caption style or font: pair Korean speech with a Hangul style explicitly."},"script_text":{"type":"string","minLength":1,"maxLength":8000,"description":"Optional predetermined caption copy. When provided, Sume keeps speech-to-text word timings as the timing source of truth and aligns burned-in wording to this script via an internal alignment step. Alignment failures soft-fail inline captions with typed public_reason `script_alignment_mismatch` or `script_alignment_failed` (no silent STT wording burn); omit script_text to derive copy from the spoken script (derived path may fall back to STT wording on mismatch). Only valid when enabled is true. Raw transcripts, cue lists, SRT content, renderer fields, and provider task ids remain unsupported."}}},"soundtrack":{"type":"object","additionalProperties":false,"description":"Optional soundtrack for Avatar Video package post-production. Exactly one of prompt or audio_url is required (xor; no mode enum). prompt: Music 1.0 generate then ffmpeg mux (Music 1.0 estimate reserved). audio_url: public HTTPS BYO BGM → mirror into Sume media then mux only (no Music reservation; the mux is free). Standalone POST /v1/music-1.0/generate remains unchanged. Create/preview validate URL shape; full accessibility is checked at generate-video (soft-fail if dead).","properties":{"prompt":{"type":"string","minLength":1,"maxLength":5000,"description":"Music 1.0 text prompt used to generate the BGM bed. Mutually exclusive with audio_url."},"audio_url":{"type":"string","format":"uri","description":"Public HTTPS URL of an existing BGM audio file to mux under the talking-head. Mutually exclusive with prompt. Localhost/private URLs are rejected. Prefer a durable public URL; the worker mirrors into Sume media before mux when possible."},"volume":{"type":"number","minimum":0.05,"maximum":0.4,"default":0.15,"description":"Linear BGM volume for mux under speech. Defaults to 0.15 (skill-lab Stage P default)."}}}}},"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}}},"AvatarVideoPreviewRegenerateRequest":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","sync","subscribe","webhook"],"description":"How the client learns the outcome. Every mode returns the job id in the first response. async (the default) returns immediately with polling URLs. sync and subscribe are aliases for the same bounded wait: they block for at most wait_timeout_seconds (max 30) when waiter capacity is available, and are not a long-lived subscription, an event stream, or a progress feed. webhook returns immediately and stores a callback for terminal delivery only. Prefer async or webhook for new integrations; for waits longer than 30 seconds, submit with async and poll status_url from the client. Note that `subscribe` here is unrelated to the SDK's subscribeFormatRun (a client-side poll loop) and to a run's communication.mode, whose only values are async and webhook."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS callback URL. Localhost, private-network, and non-HTTPS URLs are rejected. Sume stores this URL for terminal job callback delivery when completion delivery is enabled. Delivery is terminal-only (job.completed, job.failed, job.canceled); there are no progress or partial callbacks, so keep status_url polling available as a backup. Sending this without an explicit mode selects mode webhook."},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30,"description":"Blocking wait budget for mode sync or subscribe, in seconds, clamped to 0-30. This bounds how long the HTTP request blocks, not how long the job may take: video, avatar-video, and face-swap jobs routinely outlast it. If no terminal update occurs before the timeout, or the API process has no available waiter capacity, the response is still 2xx and returns the current queued or processing job state with polling URLs. Continue with status_url and honor next_poll_after_seconds; do not submit a second paid job for the same intent."}},"description":"Regenerate first-frame stills for an existing Avatar Video preview. Reuses the stored preview request (avatar, script/video_inputs, scene, quality, aspect ratio). Optional communication fields only. Returns the same avatar_video_preview_id with a new preview_only job."},"AvatarVideoPreviewGenerateVideoRequest":{"type":"object","additionalProperties":false,"properties":{"quality":{"type":"string","enum":["standard","plus","max"],"description":"Optional final-render quality override (`standard` | `plus` | `max`). When omitted (or body is empty/`{}`), the stored preview quality is used. Preview stills are tier-independent and always reused; only the final video quality tier changes. Structural fields (script, avatar, scene, aspect_ratio) cannot be changed here — create a new preview instead."}},"description":"Optional body for generate-video. Empty body or `{}` preserves today's behavior (stored preview request, including quality). Passing `quality` overrides the final render tier without paying for a new preview."},"PublicAvatarVideoScene":{"type":"object","required":["start_time_seconds","end_time_seconds","segment_type","transcript","visual_description","action_description","on_screen_text","product_mentions","brand_mentions","narrative_role","camera_framing","camera_motion","setting","people_or_subjects","cta_present","confidence"],"properties":{"start_time_seconds":{"type":"number","minimum":0},"end_time_seconds":{"type":"number","minimum":0},"segment_type":{"type":"string","enum":["hook","problem","agitate","product_demo","product_reveal","proof","result","offer","cta","transition","other"]},"transcript":{"type":"string"},"visual_description":{"type":"string"},"action_description":{"type":"string"},"on_screen_text":{"type":"array","items":{"type":"string"}},"product_mentions":{"type":"array","items":{"type":"string"}},"brand_mentions":{"type":"array","items":{"type":"string"}},"narrative_role":{"type":"string"},"camera_framing":{"type":"string"},"camera_motion":{"type":"string"},"setting":{"type":"string"},"people_or_subjects":{"type":"array","items":{"type":"string"}},"cta_present":{"type":"boolean","nullable":true},"confidence":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"number"},{"type":"null"}]}}},"PublicAvatarVideoMetadataSummary":{"type":"object","required":["status","tags","summary","scenes_count","transcript_present","updated_at","completed_at"],"properties":{"status":{"type":"string","enum":["queued","processing","ready","failed"],"description":"Video metadata enrichment status. Provider task identifiers and internal indexes are intentionally omitted."},"tags":{"type":"array","items":{"type":"string"}},"summary":{"type":"object","nullable":true,"additionalProperties":true,"properties":{"scene_count":{"type":"integer","minimum":0},"duration_seconds":{"type":"number","minimum":0},"transcript_present":{"type":"boolean"},"transcript_word_count":{"type":"integer","minimum":0},"subject":{"type":"string","nullable":true},"action":{"type":"string","nullable":true},"setting":{"type":"string","nullable":true},"style_mood":{"type":"array","items":{"type":"string"}},"visual_descriptors":{"type":"array","items":{"type":"string"}},"action_descriptors":{"type":"array","items":{"type":"string"}},"product_signals":{"type":"array","items":{"type":"string"}},"brand_signals":{"type":"array","items":{"type":"string"}},"on_screen_text_present":{"type":"boolean"},"cta_present":{"type":"boolean"},"scene_types":{"type":"array","items":{"type":"string"}}},"description":"Provider-independent review and search signals derived from public scene metadata."},"scenes_count":{"type":"integer","minimum":0,"description":"Count of public metadata scenes when available. The list endpoint does not include full scene bodies."},"transcript_present":{"type":"boolean","description":"Whether detailed metadata readback has transcript text available."},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"description":"Lightweight public-safe video metadata summary for list responses and job result linked resources. Full scenes and transcript text are intentionally omitted here and are available on avatar-video and video-asset detail endpoints."},"PublicAvatarVideoMetadata":{"type":"object","required":["status","scenes","transcript_text","tags","summary","error","updated_at","completed_at"],"properties":{"status":{"type":"string","enum":["queued","processing","ready","failed"],"description":"Video metadata enrichment status. Provider task identifiers and internal indexes are intentionally omitted."},"scenes":{"type":"array","items":{"$ref":"#/components/schemas/PublicAvatarVideoScene"}},"transcript_text":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"summary":{"type":"object","nullable":true,"additionalProperties":true,"properties":{"scene_count":{"type":"integer","minimum":0},"duration_seconds":{"type":"number","minimum":0},"transcript_present":{"type":"boolean"},"transcript_word_count":{"type":"integer","minimum":0},"subject":{"type":"string","nullable":true},"action":{"type":"string","nullable":true},"setting":{"type":"string","nullable":true},"style_mood":{"type":"array","items":{"type":"string"}},"visual_descriptors":{"type":"array","items":{"type":"string"}},"action_descriptors":{"type":"array","items":{"type":"string"}},"product_signals":{"type":"array","items":{"type":"string"}},"brand_signals":{"type":"array","items":{"type":"string"}},"on_screen_text_present":{"type":"boolean"},"cta_present":{"type":"boolean"},"scene_types":{"type":"array","items":{"type":"string"}}},"description":"Provider-independent review and search signals derived from public scene metadata."},"error":{"anyOf":[{"$ref":"#/components/schemas/PublicDeveloperApiJobError"},{"type":"null"}]},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"description":"Rich public-safe video metadata generated asynchronously after avatar-video completion. Detail readback returns this full shape by default, including normalized summary fields, tags, transcript text, and public scene metadata. Raw provider task ids, URLs, indexes, and model names are not part of this contract."},"PublicAvatarVideo":{"type":"object","required":["id","avatar_id","request_id","status","resource_status","job_status","created_at","updated_at","completed_at","video_url","preview_image_url","scene","scene_previews","artifacts","metadata","captions","package","quality","result","error"],"properties":{"id":{"type":"string"},"avatar_id":{"type":"string","description":"Read-only durable avatar resource id linked to this generated video. Use `avatar_handle` in launch generation requests."},"request_id":{"type":"string"},"quality":{"type":"string","enum":["standard","plus","max"],"description":"Effective Avatar Video quality tier for this resource (`standard` | `plus` | `max`). For generate-video with an optional quality override, this is the overridden tier used for admission, reservation, and provider submit — not necessarily the preview-create tier."},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"description":"Backward-compatible job lifecycle status. Prefer `resource_status` for resource readiness and `job_status` for job polling state."},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"],"description":"Resource-facing avatar-video state. Completed jobs map to `ready`; queued/processing jobs map to `processing`."},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true,"description":"Underlying Sume job lifecycle status, or null if no linked job is available."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"video_url":{"type":"string","format":"uri","nullable":true},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Primary public Sume-hosted Avatar Video preview image URL when available. For multi-scene previews this is the scene-0 first frame; `scene_previews[]` carries one still per input scene. Later scene stills are pose-anchored continuations of that first frame when using a shared scene."},"scene":{"type":"object","nullable":true,"required":["type","status","preview_image_url"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"]},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"]},"preview_image_url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri"}},"additionalProperties":false},"scene_previews":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicAvatarVideoScenePreview"},"description":"Ordered public-safe scene preview metadata. For multi-scene Avatar Video previews, each entry corresponds to one `video_inputs` scene. Scene 0 is the first-frame image; later scenes are pose-anchored continuations of that first frame when using a shared scene. Raw dialogue, prompt text, provider ids, provider URLs, and internal task keys are omitted."},"artifacts":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicArtifact"}},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoMetadata"},{"type":"null"}],"description":"Rich public-safe metadata for this avatar-video detail response. Includes normalized summary fields, tags, transcript text, and full public scene metadata when processing is ready."},"captions":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoCaptions"},{"type":"null"}],"description":"Inline captions summary when requested on create/generate via top-level captions or package.captions. Null when captions were omitted or disabled."},"package":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoPackage"},{"type":"null"}],"description":"Package post-production summary when package was requested. Null when package was omitted. Captions then mux order is server-enforced when both package.captions and package.soundtrack are set."},"result":{"type":"object","nullable":true,"additionalProperties":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}}},"PublicAvatarVideoPreview":{"type":"object","required":["id","avatar_id","request_id","status","resource_status","job_status","created_at","updated_at","completed_at","video_url","preview_image_url","scene","scene_previews","artifacts","metadata","captions","package","quality","result","error"],"properties":{"id":{"type":"string"},"avatar_id":{"type":"string","description":"Read-only durable avatar resource id linked to this generated video. Use `avatar_handle` in launch generation requests."},"request_id":{"type":"string"},"quality":{"type":"string","enum":["standard","plus","max"],"description":"Effective Avatar Video quality tier for this resource (`standard` | `plus` | `max`). For generate-video with an optional quality override, this is the overridden tier used for admission, reservation, and provider submit — not necessarily the preview-create tier."},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"description":"Backward-compatible job lifecycle status. Prefer `resource_status` for resource readiness and `job_status` for job polling state."},"resource_status":{"type":"string","enum":["processing","ready","failed","canceled","archived"],"description":"Resource-facing avatar-video state. Completed jobs map to `ready`; queued/processing jobs map to `processing`."},"job_status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"nullable":true,"description":"Underlying Sume job lifecycle status, or null if no linked job is available."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"video_url":{"type":"string","format":"uri","nullable":true},"preview_image_url":{"type":"string","format":"uri","nullable":true,"description":"Primary public Sume-hosted Avatar Video preview image URL when available. For multi-scene previews this is the scene-0 first frame; `scene_previews[]` carries one still per input scene. Later scene stills are pose-anchored continuations of that first frame when using a shared scene."},"scene":{"type":"object","nullable":true,"required":["type","status","preview_image_url"],"properties":{"type":{"type":"string","enum":["prompt","photo","none"]},"status":{"type":"string","enum":["queued","processing","ready","failed","canceled"]},"preview_image_url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri"}},"additionalProperties":false},"scene_previews":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicAvatarVideoScenePreview"},"description":"Ordered public-safe scene preview metadata. For multi-scene Avatar Video previews, each entry corresponds to one `video_inputs` scene. Scene 0 is the first-frame image; later scenes are pose-anchored continuations of that first frame when using a shared scene. Raw dialogue, prompt text, provider ids, provider URLs, and internal task keys are omitted."},"artifacts":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/PublicArtifact"}},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoMetadata"},{"type":"null"}],"description":"Rich public-safe metadata for this avatar-video detail response. Includes normalized summary fields, tags, transcript text, and full public scene metadata when processing is ready."},"captions":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoCaptions"},{"type":"null"}],"description":"Inline captions summary when requested on create/generate via top-level captions or package.captions. Null when captions were omitted or disabled."},"package":{"anyOf":[{"$ref":"#/components/schemas/PublicAvatarVideoPackage"},{"type":"null"}],"description":"Package post-production summary when package was requested. Null when package was omitted. Captions then mux order is server-enforced when both package.captions and package.soundtrack are set."},"result":{"type":"object","nullable":true,"additionalProperties":true},"error":{"$ref":"#/components/schemas/PublicDeveloperApiJobError"}},"description":"Public-safe Avatar Video preview resource. This resource represents first-frame preview generation only; video_url remains null until a separate final Avatar Video resource is created through generate-video."},"AvatarVideoSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","avatar_video_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits","job","avatar_video","sync"],"properties":{"request_id":{"type":"string"},"avatar_video_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"avatar_video":{"$ref":"#/components/schemas/PublicAvatarVideo"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"AvatarVideoPreviewSubmitResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","avatar_video_preview_id","status_url","result_url","events_url","cancel_url","cancelable","next_action","next_poll_after_seconds","recommended_poll_interval_seconds","retry_after_seconds","result_ready","terminal","idempotency_hit","usage","generation_limits","job","preview","sync"],"properties":{"request_id":{"type":"string"},"avatar_video_preview_id":{"type":"string"},"status_url":{"type":"string","format":"uri","description":"Poll this URL for current queue/job status."},"result_url":{"type":"string","format":"uri","description":"Fetch this URL after `result_ready` is true. Non-completed jobs return 409 job_not_completed."},"events_url":{"type":"string","format":"uri","description":"Fetch this URL for sanitized lifecycle, generation, terminal, and webhook delivery events."},"cancel_url":{"type":"string","format":"uri","nullable":true,"description":"POST this URL to cancel while `cancelable` is true. Null after generation starts and after terminal states."},"cancelable":{"type":"boolean","description":"True only before external generation work has started and the job can still be canceled through `cancel_url`."},"next_action":{"type":"string","enum":["poll_status","fetch_result","inspect_events"],"description":"`poll_status` for queued/processing jobs, `fetch_result` once completed, and `inspect_events` for failed/canceled terminal jobs."},"next_poll_after_seconds":{"type":"integer","nullable":true,"description":"Suggested minimum delay before the next status poll. Null for terminal jobs."},"recommended_poll_interval_seconds":{"type":"integer","nullable":true,"description":"Default SDK/CLI polling cadence for non-terminal jobs. Null for terminal jobs."},"retry_after_seconds":{"type":"integer","nullable":true,"description":"Backoff hint when Sume has delayed the next worker attempt. Null when no special backoff applies."},"result_ready":{"type":"boolean","description":"True only when `/result` can return 200 with a result body."},"terminal":{"type":"boolean","description":"True when the job is completed, failed, or canceled and normal polling can stop."},"idempotency_hit":{"type":"boolean"},"usage":{"type":"object","description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms.","required":["credits"],"properties":{"credits":{"type":"integer","minimum":0,"description":"Credits this request is charged: what the reservation holds and capture settles for the authenticated workspace, after its own terms. Rounded up, so a paid request never reads 0."},"usd":{"type":"string","pattern":"^\\d+\\.\\d{2}$","description":"The same charge in US dollars, rounded up to the cent (a paid request never reads 0.00): the amount to quote to a person. On an admission preview this is the list price; when `generation_ticket` is present quote `cost` instead."},"cost":{"type":"number","minimum":0,"description":"US dollars this run is charged, after any discount. Present only with `generation_ticket`: a run of a ticket model while the account holds or used tickets, or on an Open-product key. A run that HeyGen tickets cover reads 0."},"cost_details":{"type":"object","additionalProperties":false,"required":["list_cost","discount","discount_source"],"description":"How `cost` was reached: the list price, the discount taken off it and where the discount came from.","properties":{"list_cost":{"type":"number","minimum":0,"description":"US dollars at list price, before tickets."},"discount":{"type":"number","minimum":0,"description":"US dollars taken off the list price."},"discount_source":{"type":"string","nullable":true,"enum":["generation_ticket",null],"description":"`generation_ticket` when tickets paid for the run, null when nothing was taken off."}}},"generation_ticket":{"type":"object","additionalProperties":false,"required":["kind","state","tickets_needed","tickets_used"],"description":"Tickets for this run. `covered`: the run spent `tickets_used` tickets and `cost` is 0. `insufficient`: the account holds fewer than `tickets_needed`, so no ticket was spent and the run is charged as usual. `returned`: the run failed or was refunded and its tickets came back. `not_applicable`: no ticket was spent though tickets pay for this model, and `reason` says why — `open_key` (Open-product API keys never use tickets), `provider_route` (tickets pay only for runs on HeyGen's own API, and these settings run elsewhere), `heygen_budget` (HeyGen's ticket budget cannot cover this run now) or `unpriced` (the run's HeyGen cost could not be priced). The run is charged as usual and the account keeps its tickets.","properties":{"kind":{"type":"string","description":"Ticket kind, e.g. `heygen_video_1`."},"state":{"type":"string","enum":["covered","insufficient","returned","not_applicable"]},"tickets_needed":{"type":"integer","minimum":1,"description":"Tickets the run needs: its list price over one 480p 5 s text-to-video run, rounded half up."},"tickets_used":{"type":"integer","minimum":0,"description":"Tickets this run spent (0 unless `covered`)."},"tickets_returned":{"type":"integer","minimum":0,"description":"Tickets given back, when `state` is `returned`."},"tickets_held":{"type":"integer","minimum":0,"description":"Tickets the account holds now (a quote, `insufficient`, or `not_applicable` other than `open_key`)."},"tickets_remaining":{"type":"integer","minimum":0,"description":"Tickets the account holds after this run."},"reason":{"type":"string","enum":["open_key","provider_route","heygen_budget","unpriced","workspace"],"description":"Why tickets do not apply."}}}}},"generation_limits":{"$ref":"#/components/schemas/PublicGenerationLimits"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"},"preview":{"$ref":"#/components/schemas/PublicAvatarVideoPreview"},"sync":{"type":"object","nullable":true,"description":"Sync/subscribe wait outcome. `completed` is true only when the job succeeded and `/result` is ready. `terminal` is true for completed, failed, or canceled jobs. `timed_out` is true when the response returned before a terminal state. `capacity_exhausted` is true when the API skipped the blocking wait because the per-process waiter budget was full.","required":["wait_timeout_seconds","completed","terminal","succeeded","failed","canceled","result_ready","timed_out","capacity_exhausted"],"properties":{"wait_timeout_seconds":{"type":"integer","description":"Sync wait budget requested by the client."},"completed":{"type":"boolean","description":"Backward-compatible success flag. True only when `job.status` is `completed` and `/result` is available."},"terminal":{"type":"boolean","description":"True when `job.status` is `completed`, `failed`, or `canceled`."},"succeeded":{"type":"boolean","description":"True when `job.status` is `completed`."},"failed":{"type":"boolean","description":"True when `job.status` is `failed`."},"canceled":{"type":"boolean","description":"True when `job.status` is `canceled`."},"result_ready":{"type":"boolean","description":"True when a GET to `result_url` can return a completed result payload."},"timed_out":{"type":"boolean","description":"True when the sync wait returned before the job reached a terminal state."},"capacity_exhausted":{"type":"boolean","description":"True when the API skipped the blocking sync/subscribe wait because this process had no remaining waiter capacity. Clients should poll `status_url` instead."}}}}}}},"AvatarVideoPreviewResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["avatar_video_preview_id","preview","job"],"properties":{"avatar_video_preview_id":{"type":"string"},"preview":{"$ref":"#/components/schemas/PublicAvatarVideoPreview"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"AvatarVideoResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["avatar_video","job"],"properties":{"avatar_video":{"$ref":"#/components/schemas/PublicAvatarVideo"},"job":{"$ref":"#/components/schemas/PublicDeveloperApiJob"}}}}},"RunWebhookEvent":{"type":"object","description":"Terminal callback body POSTed to a run's `communication.webhook_url`. Sume signs the raw JSON with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1` HMAC, the same scheme as job webhooks); return any 2xx after durable processing. Non-2xx and transport failures are retried with exponential backoff up to 10 attempts; HTTP 429/503 `Retry-After` is honoured (delay is the longer of exponential backoff and Retry-After, capped at 1h) and exhausted attempts surface as `webhook_delivery.status: exhausted`. A `canceled` or `skipped` run never delivers. Delivery is live on both `api.dev.sume.com` and `api.sume.com`.","required":["event","request_id","run_id","object","status","outcome","created_at","payload","error"],"properties":{"event":{"type":"string","enum":["action.run.terminal","format.run.terminal","agent.run.terminal"],"description":"One terminal event per run family. Route on this without inspecting the body."},"request_id":{"type":"string","description":"Equals `run_id` and is stable across retries — the dedupe key."},"run_id":{"type":"string","description":"The run this delivery is about."},"object":{"type":"string","enum":["action.run","format.run","agent.run"],"description":"The receipt's own `object`."},"status":{"type":"string","enum":["OK","ERROR"],"description":"`OK` when the run completed; `ERROR` for every other terminal state. Reports the run's real outcome even when `payload` had to be dropped for size. Binary by design — branch on `outcome` when you need to know whether usable output arrived."},"outcome":{"type":"string","enum":["ok","degraded","error"],"description":"Finer-grained than `status`. `ok` — completed with output. `degraded` — completed and billed, with real media in `artifacts[]`, but the structured projection did not match your schema, so `output` is null and `output_error` says why. `error` — the run did not complete. A handler that treats `status: \"OK\"` as \"I have output\" should branch here instead."},"created_at":{"type":"string","format":"date-time","description":"When this delivery body was built. Use it to order deliveries; the envelope's `request_id` is the run id and is stable across retries, so it cannot order them."},"payload":{"description":"The run receipt — byte-identical to the `data` object of `GET /v1/{family}-runs/{run_id}` for the same run, so one handler serves poll and webhook. Null only when the receipt exceeded the body cap; `error.result_url` then says where to fetch it.","oneOf":[{"$ref":"#/components/schemas/PublicActionRun"},{"$ref":"#/components/schemas/PublicFormatRun"},{"$ref":"#/components/schemas/PublicAgentRun"},{"type":"null"}]},"error":{"type":["object","null"],"required":["code","message"],"description":"Null when `status` is `OK`. Mirrors `payload.error` for a failed run; supplied by the envelope for `canceled` runs, which are an outcome rather than a failure and so carry no receipt error.","properties":{"code":{"type":"string"},"message":{"type":"string"},"result_url":{"type":"string","format":"uri","description":"Only on `payload_too_large` — a receipt over 1048576 bytes is not delivered inline. Fetch the receipt here instead."}}}},"example":{"event":"format.run.terminal","request_id":"arun_0123456789abcdef","run_id":"arun_0123456789abcdef","object":"format.run","status":"OK","payload":{"id":"arun_0123456789abcdef","object":"format.run","status":"completed","format":{"id":"skl_0123456789abcdef","slug":"product-promo","title":"Product promo","version":3},"output":{"text":"..."},"result_url":"https://api.sume.com/v1/format-runs/arun_0123456789abcdef/result"},"error":null}}}},"paths":{"/v1/workspaces":{"get":{"operationId":"listWorkspaces","summary":"List the workspaces you can switch to","tags":["Account"],"description":"Lists the signed-in person's personal workspace and the teams they belong to, with the one this connection works in marked `is_selected`. A Sume sign-in (an MCP connection or `sume login`) can switch with `POST /v1/workspaces/select`; an API key belongs to one workspace and lists only that one.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Workspaces the signed-in person can work in, with the selected one marked.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/workspaces/select":{"post":{"operationId":"selectWorkspace","summary":"Switch the workspace this connection works in","tags":["Account"],"description":"Moves a Sume sign-in to another workspace the person belongs to. From the next request on, generations bill that workspace and reads see its assets and jobs; the connection's refresh token keeps the choice. Spends nothing. An API key cannot switch (`409 workspace_fixed`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["workspace_id"],"additionalProperties":false,"properties":{"workspace_id":{"type":"string","minLength":1,"maxLength":128}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"The workspace this connection works in from the next request on.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceSelectionResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The person is not a member of that workspace (`workspace_not_allowed`).","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"This credential belongs to one workspace and cannot switch (`workspace_fixed`).","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/files/generate-upload-url":{"post":{"operationId":"generateUploadUrl","summary":"Get a URL to upload a file","tags":["Open"],"description":"One call before an upload: returns `upload_url` to PUT the bytes to and `public_url` to pass to a model as soon as the PUT finishes. No completion call is needed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["content_type","size_bytes"],"properties":{"content_type":{"type":"string","description":"The file's MIME type, such as `image/png`, `video/mp4` or `audio/wav`. The PUT must send the same `content-type`."},"size_bytes":{"type":"integer","minimum":1,"description":"The file's exact size. It is signed into `upload_url`, so the PUT body must be exactly this long."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The original file name, kept on the asset."}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"201":{"description":"Where to upload, and where the file will be.","content":{"application/json":{"schema":{"description":"Where to upload, and where the file will be.","type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["public_url","upload_url","upload_method","upload_headers","content_type","expires_at","asset_id"],"properties":{"public_url":{"type":"string","description":"The file's HTTPS address once uploaded. Send it in `image_url`, `video_url`, `audio_url` or any other input URL field."},"upload_url":{"type":"string","description":"A short-lived presigned URL. PUT the bytes to it, without your API key. Do not log it."},"upload_method":{"type":"string","enum":["PUT"]},"upload_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Send exactly these headers with the PUT."},"content_type":{"type":"string"},"expires_at":{"type":"string","description":"When `upload_url` stops accepting the PUT (ISO 8601)."},"asset_id":{"type":"string","description":"The upload's asset id, for the optional `POST /v1/assets/{id}/complete`."}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"`asset_too_large`: `size_bytes` is over the upload limit (`details.max_bytes`).","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"`asset_store_not_configured` or `asset_storage_not_configured`: uploads are not available in this environment.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/health":{"get":{"operationId":"getVersionedHealth","summary":"Versioned API health","tags":["Health"],"responses":{"200":{"description":"Versioned public API health.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionHealthResponse"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/catalog":{"get":{"operationId":"listPublicApiCapabilities","summary":"List public API capabilities","tags":["Catalog"],"description":"Returns the public capability catalog. Paid capabilities include Sume pricing in credits where available and require their documented API and worker environment configuration for submission, polling, artifacts, usage settlement, and callbacks.","responses":{"200":{"description":"Public capability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/bgm/catalog":{"get":{"operationId":"listBgmCatalog","summary":"List curated BGM catalog","tags":["BGM"],"description":"Returns the Assets → BGM catalog with optional category/mood/genre/energy filters. First-party Sume loops are served from `/assets/bgm` (override with SUME_BGM_ASSET_BASE_URL). Featured beds are Kevin MacLeod / Incompetech tracks (CC BY 4.0) at their official URLs — keep `track.attribution` with any public use. Existing first-party ids stay stable. No per-user upload for MVP.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"string"},"in":"query","name":"mood","required":false},{"schema":{"type":"string"},"in":"query","name":"genre","required":false},{"schema":{"type":"string","enum":["calm","upbeat","dramatic","neutral"]},"in":"query","name":"energy","required":false},{"schema":{"type":"string"},"in":"query","name":"tag","required":false},{"schema":{"type":"string"},"in":"query","name":"video_genre","required":false},{"schema":{"type":"string"},"in":"query","name":"product_category","required":false},{"schema":{"type":"string"},"in":"query","name":"locale","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/bgm/categories":{"get":{"operationId":"listBgmCategories","summary":"List BGM catalog categories","tags":["BGM"],"description":"Returns the non-empty BGM categories with track counts, for category browsing in Assets → BGM and the video editor.","responses":{"200":{"description":"Default Response"}}}},"/v1/bgm/pick":{"post":{"operationId":"pickBgmTrack","summary":"Pick contextual BGM","tags":["BGM"],"description":"Scores the curated catalog against a situation context (mood, genre, energy, tags, product category, user prompt). Widens filters when no strong match; tie-break is deterministic among top scores — not Math.random().","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"context":{"type":"object","additionalProperties":true},"min_score":{"type":"number","minimum":0},"auto_expand":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/firecrawl/scrape":{"post":{"operationId":"firecrawl_scrape","summary":"Web crawl scrape","tags":["Web crawl"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"formats":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"string","enum":["markdown","links","html","json","screenshot","rawHtml","images"]},"default":["markdown"]},"json_schema":{"type":"object","additionalProperties":true},"json_prompt":{"type":"string","minLength":1,"maxLength":2000},"only_main_content":{"type":"boolean","default":true},"timeout_ms":{"type":"integer","minimum":1,"maximum":30000,"default":30000},"wait_for_ms":{"type":"integer","minimum":0,"maximum":10000},"fresh":{"type":"boolean","default":false},"actions":{"type":"array","maxItems":8,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["wait"]},"milliseconds":{"type":"integer","minimum":1,"maximum":10000}},"required":["type","milliseconds"]},{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["scroll"]},"direction":{"type":"string","enum":["up","down"]},"selector":{"type":"string","minLength":1,"maxLength":500}},"required":["type","direction"]},{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["click"]},"selector":{"type":"string","minLength":1,"maxLength":500}},"required":["type","selector"]},{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["executeJavascript"]},"script":{"type":"string","minLength":1,"maxLength":4000}},"required":["type","script"]}]}}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/firecrawl/map":{"post":{"operationId":"firecrawl_map","summary":"Web crawl map","tags":["Web crawl"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"limit":{"type":"integer","minimum":1,"maximum":100,"default":100}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/firecrawl/search":{"post":{"operationId":"firecrawl_search","summary":"Web crawl search","tags":["Web crawl"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":500},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/firecrawl/crawl":{"post":{"operationId":"firecrawl_crawl","summary":"Web crawl crawl","tags":["Web crawl"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10},"include_paths":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^/","maxLength":200}},"exclude_paths":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^/","maxLength":200}},"formats":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"string","enum":["markdown","links","html","json","screenshot","rawHtml","images"]},"default":["markdown"]},"json_schema":{"type":"object","additionalProperties":true},"json_prompt":{"type":"string","minLength":1,"maxLength":2000},"only_main_content":{"type":"boolean","default":true},"timeout_ms":{"type":"integer","minimum":1,"maximum":30000,"default":30000},"wait_for_ms":{"type":"integer","minimum":0,"maximum":10000},"fresh":{"type":"boolean","default":false},"actions":{"type":"array","maxItems":8,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["wait"]},"milliseconds":{"type":"integer","minimum":1,"maximum":10000}},"required":["type","milliseconds"]},{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["scroll"]},"direction":{"type":"string","enum":["up","down"]},"selector":{"type":"string","minLength":1,"maxLength":500}},"required":["type","direction"]},{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["click"]},"selector":{"type":"string","minLength":1,"maxLength":500}},"required":["type","selector"]},{"type":"object","additionalProperties":false,"properties":{"type":{"enum":["executeJavascript"]},"script":{"type":"string","minLength":1,"maxLength":4000}},"required":["type","script"]}]}}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"description":"Required stable key for crawl submission. Retry the same intent with the same key to adopt the original job; a different payload with the same key returns 409 idempotency_conflict."}]}},"/v1/firecrawl/crawls/{id}":{"get":{"operationId":"firecrawl_crawl_get","summary":"Get a workspace web crawl job","tags":["Web crawl"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/image-1.0/generate":{"post":{"operationId":"generateImageV1","summary":"Generate Image 1.0 asset (retiring soon)","tags":["Image 1.0"],"description":"Retiring soon. Compatibility alias for Image Router Auto (POST /v1/images with sume/auto). Optional `transparency: true` generates then removes background (Sume RMBG 1.0) per output and returns cutout PNG only; default is opaque/normal. Transparent mode bills image generation plus remove-background per image in one reservation. Provider model ids stay internal; callers use Sume-owned job URLs and the public model id `sume/auto`.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeImageGenerationRequest"},"examples":{"text_to_image":{"summary":"Text to image","value":{"prompt":"A clean product hero image for a new AI video ad platform, studio lighting, premium SaaS visual style","aspect_ratio":"1:1","quality":"high","num_images":1,"output_format":"png","mode":"async"}},"image_reference_edit":{"summary":"Image reference/edit","value":{"prompt":"Create a polished product ad image using the reference UI and premium studio lighting.","image_urls":["https://example.com/inputs/product-reference.png"],"image_size":"landscape_16_9","quality":"high","num_images":1,"output_format":"png"}},"webhook_usage":{"summary":"Webhook callback","value":{"prompt":"A vertical launch image for a creator analytics dashboard.","aspect_ratio":"9:16","num_images":1,"mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"deprecated":true,"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Image generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Image generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/image-1.0/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"prompt\": \"A clean product hero image for a new AI video ad platform, studio lighting, premium SaaS visual style\",\n  \"aspect_ratio\": \"1:1\",\n  \"quality\": \"high\",\n  \"num_images\": 1,\n  \"output_format\": \"png\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/image-router/models":{"get":{"operationId":"listImageRouterModels","summary":"List Image Router models","tags":["Image Router"],"description":"Catalog of explicit pass-through image models (model-in-body invoke). Separate from Sume Image 1.0. Each model lists its credits per image.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Image Router catalog listing pass-through models with capabilities and pricing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageRouterModelsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/image-router/models/{model_id}":{"get":{"operationId":"getImageRouterModel","summary":"Get Image Router model","tags":["Image Router"],"description":"Return one Image Router catalog model by id. Returns 404 when the model id is not in the seed catalog.","parameters":[{"schema":{"type":"string"},"in":"path","name":"model_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Image Router catalog model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageRouterModelResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/image-router/generate":{"post":{"operationId":"generateImageRouter","summary":"Generate via Image Router","tags":["Image Router"],"description":"Explicit pass-through image generation. Requires `model` from GET /v1/image-router/models. job.model equals the requested routable id. Reuses the Sume async job lifecycle and credits billing.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeImageRouterGenerationRequest"},"examples":{"gpt_image_2":{"summary":"GPT Image 2 text-to-image","value":{"model":"gpt-image-2","prompt":"Product hero on white seamless background, soft studio light.","aspect_ratio":"1:1","quality":"high","num_images":1,"output_format":"png","mode":"async"}},"nano_banana_21":{"summary":"Nano Banana 2.1 text-to-image","value":{"model":"nano-banana-2.1","prompt":"Minimal product packshot on matte concrete.","aspect_ratio":"1:1","resolution":"1K","mode":"async"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Image Router job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"nano-banana-2.1","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"gpt-image-2","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Image Router job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"nano-banana-2.1","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"gpt-image-2","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/image-router/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"model\": \"gpt-image-2\",\n  \"prompt\": \"Product hero on white seamless background, soft studio light.\",\n  \"aspect_ratio\": \"1:1\",\n  \"quality\": \"high\",\n  \"num_images\": 1,\n  \"output_format\": \"png\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/images/models":{"get":{"operationId":"listImageModels","summary":"List image generation models","tags":["Images"],"description":"Image model catalog with per-model capability descriptors. A request parameter absent from a model's supported_parameters is rejected with unsupported_parameter.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Image model catalog with per-model capability descriptors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageModelsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/images/models/{*}":{"get":{"operationId":"listImageModelEndpoints","summary":"List image model endpoints","tags":["Images"],"description":"Definitive per-endpoint capabilities and billable pricing for one image model. Sume publishes a single `sume` endpoint per model in v1.","security":[{"apiKey":[]},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Per-endpoint capabilities and billable pricing for one image model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageModelEndpointsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/images":{"post":{"operationId":"createImage","summary":"Create images","tags":["Images"],"description":"Generate images from a prompt and optional reference images. Blocks for up to 30s and returns the image response; generations that exceed the budget return 202 with the Sume job envelope instead, and generations that terminally fail inside the budget return the remapped public reason with a status for the cause: 422 for a rejected input, 503 when a retry can succeed, 500 otherwise. A job Sume could not start is 502 `provider_submission_failed`. Accepts `sume/auto` without disclosing which family served the request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeImagesGenerationRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Completed image generation. Generations that exceed the sync wait budget return the job envelope with 202 instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request used the default synchronous wait and the generation terminally failed inside the budget — a failed synchronous generation is a terminal error, not a pollable job. The status follows the cause: `422` when the model rejected the input (`next_action: fix_input`), `503` when a retry can succeed (`retryable: true`), and `500` when it failed for good. `error.code`, `error.message` and the actionability fields are the same public remap `GET /v1/jobs/{id}/status` reports, and `error.details.status_url` polls the job for the full record.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/video-1.0/generate":{"post":{"operationId":"generateVideoV1","summary":"Generate Video 1.0 asset (retiring soon)","tags":["Video 1.0"],"description":"Retiring soon. Compatibility alias for Video Router Auto (POST /v1/videos with sume/auto). Legacy routing_preset is ignored; the Auto family validates supported parameters.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoGenerationRequest"},"examples":{"text_to_video":{"summary":"Text to video","value":{"prompt":"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.","resolution":"720p","duration":8,"aspect_ratio":"9:16","generate_audio":false,"routing_preset":"cost","mode":"async"}},"image_to_video":{"summary":"Image to video with first/end frames","value":{"prompt":"Animate the subject with subtle camera movement and realistic hand motion. Keep the face stable.","image_url":"https://example.com/inputs/first-frame.png","end_image_url":"https://example.com/inputs/end-frame.png","resolution":"720p","duration":8,"aspect_ratio":"9:16","generate_audio":false}},"reference_to_video":{"summary":"Reference to video","value":{"prompt":"Create a realistic vertical UGC ad using @Image1 and @Video1 as references. Keep the camera handheld and natural.","reference_image_urls":["https://example.com/inputs/avatar-reference.png","https://example.com/inputs/product-ui.png"],"reference_video_urls":["https://example.com/inputs/style-reference.mp4"],"resolution":"720p","duration":8,"aspect_ratio":"9:16","generate_audio":true}},"webhook_usage":{"summary":"Webhook callback","value":{"prompt":"A cinematic product reveal for a new dashboard.","duration":6,"aspect_ratio":"16:9","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"deprecated":true,"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Video generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Video generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/video-1.0/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"prompt\": \"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.\",\n  \"resolution\": \"720p\",\n  \"duration\": 8,\n  \"aspect_ratio\": \"9:16\",\n  \"generate_audio\": false,\n  \"routing_preset\": \"cost\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/video-router/models":{"get":{"operationId":"listVideoRouterModels","summary":"List Video Router models","tags":["Video Router"],"description":"Catalog of explicit pass-through video models (model-in-body invoke). Separate from Sume Video 1.0 (`routing_preset`). Each model lists its credits per unit.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video Router catalog listing pass-through models with capabilities and pricing on every row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRouterModelsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-router/models/{model_id}":{"get":{"operationId":"getVideoRouterModel","summary":"Get Video Router model","tags":["Video Router"],"description":"Return one Video Router catalog model by id. Returns 404 when the model id is not in the seed catalog.","parameters":[{"schema":{"type":"string"},"in":"path","name":"model_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Video Router catalog model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRouterModelResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-router/generate":{"post":{"operationId":"generateVideoRouter","summary":"Generate via Video Router","tags":["Video Router"],"description":"Explicit pass-through video generation. Requires `model` from GET /v1/video-router/models, or `auto-` / `sume/auto` / `auto`. job.model equals the requested routable id (auto aliases stay opaque). Reuses the Sume async job lifecycle and credits billing. Does not accept routing_preset.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoRouterGenerationRequest"},"examples":{"seedance_25":{"summary":"Seedance 2.5 text-to-video","value":{"model":"seedance-2.5","prompt":"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.","resolution":"720p","duration":12,"aspect_ratio":"9:16","generate_audio":true,"mode":"async"}},"seedance_mini":{"summary":"Seedance 2.0 Mini text-to-video","value":{"model":"seedance-2-mini","prompt":"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.","resolution":"720p","duration":5,"aspect_ratio":"9:16","generate_audio":false,"mode":"async"}},"kling":{"summary":"Kling 4 text-to-video","value":{"model":"kling-4","prompt":"Cinematic product orbit on a clean table.","resolution":"720p","duration":5,"aspect_ratio":"16:9","generate_audio":true,"mode":"async"}},"wan":{"summary":"Wan 3.0 text-to-video","value":{"model":"wan-3.0","prompt":"A red panda walking through a bamboo forest at sunrise, cinematic lighting.","resolution":"1080p","duration":5,"aspect_ratio":"16:9","generate_audio":true,"mode":"async"}},"minimaxH3":{"summary":"MiniMax H3 text-to-video","value":{"model":"minimax-h3","prompt":"A white kitten chases a butterfly across a sunlit garden. Gentle camera tracking.","resolution":"768p","duration":5,"aspect_ratio":"16:9","mode":"async"}},"geminiOmniFlash":{"summary":"Gemini Omni Flash 1.1 text-to-video","value":{"model":"gemini-omni-flash-1.1","prompt":"A cinematic wide shot of a lighthouse on a rocky cliff at dusk, waves crashing.","resolution":"1080p","duration":8,"aspect_ratio":"16:9","mode":"async"}},"geminiOmniFlashReference":{"summary":"Gemini Omni Flash 1.1 reference-to-video","value":{"model":"gemini-omni-flash-1.1","prompt":"A cat inspired by <IMAGE_REF_0> walks through the setting shown in <VIDEO_REF_0>.","reference_image_urls":["https://example.com/inputs/cat.png"],"reference_video_urls":["https://example.com/inputs/setting-3s.mp4"],"resolution":"720p","duration":8,"aspect_ratio":"16:9","mode":"async"}},"geminiOmniFlashEdit":{"summary":"Gemini Omni Flash 1.1 edit (video-to-video)","value":{"model":"gemini-omni-flash-1.1","prompt":"Replace the bottle with an apple. Keep everything else the same.","video_url":"https://example.com/inputs/clip.mp4","resolution":"720p","mode":"async"}},"grok":{"summary":"Grok Imagine image-to-video","value":{"model":"grok-imagine-video-1.5","prompt":"Subtle camera push-in with natural motion.","image_url":"https://example.com/inputs/first-frame.png","resolution":"720p","duration":6,"mode":"async"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Video Router job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"seedance-2-mini","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"seedance-2-mini","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Video Router job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"seedance-2-mini","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"seedance-2-mini","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/video-router/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"model\": \"seedance-2.5\",\n  \"prompt\": \"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.\",\n  \"resolution\": \"720p\",\n  \"duration\": 12,\n  \"aspect_ratio\": \"9:16\",\n  \"generate_audio\": true,\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/sume/remix/restyle/v1.0/presets":{"get":{"operationId":"remixRestylePresets","summary":"Sume Remix Restyle: list the styles","tags":["Sume Remix"],"description":"The styles Sume Remix Restyle takes as `preset_id`. Each item's `preview_url` is the style plate the edit uses as its reference image.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixRestylePresetsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/sume/remix/motion-transfer/v1.0":{"post":{"operationId":"remixMotionTransfer","summary":"Sume Remix Motion Transfer: transfer a video's motion to new subjects","tags":["Sume Remix"],"description":"`sume/remix/motion-transfer/v1.0`: Sume Remix Motion Transfer edits one source video from 1–8 images in `image_urls` (transfer a video's motion to new subjects). Leave out `duration` and the API reads the source's length from the file. The output follows the source's length and keeps the source's sound. Poll `GET /v1/jobs/{id}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"202":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/sume/remix/object-swap/v1.0":{"post":{"operationId":"remixObjectSwap","summary":"Sume Remix Object Swap: swap people or objects in a video","tags":["Sume Remix"],"description":"`sume/remix/object-swap/v1.0`: Sume Remix Object Swap edits one source video from 1–8 images in `image_urls` (swap people or objects in a video). Leave out `duration` and the API reads the source's length from the file. The output follows the source's length and keeps the source's sound. Poll `GET /v1/jobs/{id}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"202":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/sume/remix/restyle/v1.0":{"post":{"operationId":"remixRestyle","summary":"Sume Remix Restyle: restyle a video in one of Sume's styles","tags":["Sume Remix"],"description":"`sume/remix/restyle/v1.0`: Sume Remix Restyle restyles one source video in one of Sume's styles: `preset_id` (required, one of `GET /v1/sume/remix/restyle/v1.0/presets`) picks it, the source's first frame is redrawn in that style with the prompt, the edit restyles a depth video of the source from that frame and the style's plate, `image_urls` is not taken and the optional prompt adds to the style. Leave out `duration` and the API reads the source's length from the file. The output follows the source's length and keeps the source's sound. Poll `GET /v1/jobs/{id}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixRestyleRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"202":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/sume/remix-lite/motion-transfer/v1.0":{"post":{"operationId":"remixLiteMotionTransfer","summary":"Sume Remix Lite Motion Transfer: transfer a video's motion to new subjects","tags":["Sume Remix"],"description":"`sume/remix-lite/motion-transfer/v1.0`: Sume Remix Lite Motion Transfer edits one source video from 1–8 images in `image_urls` (transfer a video's motion to new subjects). Leave out `duration` and the API reads the source's length from the file. The output follows the source's length and keeps the source's sound. Poll `GET /v1/jobs/{id}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"202":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/sume/remix-lite/object-swap/v1.0":{"post":{"operationId":"remixLiteObjectSwap","summary":"Sume Remix Lite Object Swap: swap people or objects in a video","tags":["Sume Remix"],"description":"`sume/remix-lite/object-swap/v1.0`: Sume Remix Lite Object Swap edits one source video from 1–8 images in `image_urls` (swap people or objects in a video). Leave out `duration` and the API reads the source's length from the file. The output follows the source's length and keeps the source's sound. Poll `GET /v1/jobs/{id}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"202":{"description":"Sume Remix job envelope: the job, plus `remix` with the product, the mode and the model id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/llm-router/models":{"get":{"operationId":"listLlmRouterModels","summary":"List LLM Router models","tags":["LLM Router"],"description":"Catalog of LLM Router models. Each row's price is per million tokens, input and output; thinking tokens count as output.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["models"],"properties":{"models":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["id","name","company","modality","inputs","pricing"],"properties":{"id":{"type":"string","enum":["gemini-3.8-flash"]},"name":{"type":"string"},"company":{"type":"string"},"modality":{"type":"string"},"inputs":{"type":"array","items":{"type":"string"}},"context_tokens":{"type":"integer"},"pricing":{"type":"object","additionalProperties":true}}}}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/llm-router/models/{model_id}":{"get":{"operationId":"getLlmRouterModel","summary":"Get LLM Router model","tags":["LLM Router"],"description":"Return one LLM Router catalog model by id. Returns 404 when the model id is not in the catalog.","parameters":[{"schema":{"type":"string"},"in":"path","name":"model_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["model"],"properties":{"model":{"type":"object","additionalProperties":true,"required":["id","name","company","modality","inputs","pricing"],"properties":{"id":{"type":"string","enum":["gemini-3.8-flash"]},"name":{"type":"string"},"company":{"type":"string"},"modality":{"type":"string"},"inputs":{"type":"array","items":{"type":"string"}},"context_tokens":{"type":"integer"},"pricing":{"type":"object","additionalProperties":true}}}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/llm-router/generate":{"post":{"operationId":"generateLlmRouter","summary":"Generate text via LLM Router","tags":["LLM Router"],"description":"Runs one catalog model on a prompt, with an optional system prompt, up to 10 images and one video, and answers when the model does. `response_format: json` asks for JSON. Billed per token at the model's list price (GET /v1/llm-router/models): the request holds a ceiling (200,000 input tokens plus `max_tokens` of output) and captures the tokens the model reports.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["model","prompt"],"properties":{"model":{"type":"string","enum":["gemini-3.8-flash"],"description":"Catalog id from GET /v1/llm-router/models."},"prompt":{"type":"string","minLength":1,"maxLength":200000},"system_prompt":{"type":"string","maxLength":100000},"image_urls":{"type":"array","maxItems":10,"items":{"type":"string","format":"uri"},"description":"Up to 10 public HTTPS images (PNG, JPEG, WebP, HEIC), in order."},"video_url":{"type":"string","format":"uri","description":"One public HTTPS video the model watches, up to 100 MB."},"temperature":{"type":"number","minimum":0,"maximum":2},"max_tokens":{"type":"integer","minimum":1,"maximum":32768,"description":"Output cap, thinking included. Default 4096."},"response_format":{"type":"string","enum":["text","json"],"description":"`json` asks the model for a JSON answer."}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["model","output","finish_reason","usage"],"properties":{"model":{"type":"string"},"output":{"type":"string"},"finish_reason":{"type":["null","string"]},"usage":{"type":"object","additionalProperties":false,"required":["prompt_tokens","completion_tokens","reasoning_tokens","total_tokens","cost"],"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"reasoning_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"cost":{"type":"string","description":"What this call charged, in dollars, as a string with a leading dollar sign and six decimals."}}},"billing":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/videos/models":{"get":{"operationId":"listVideoGenerationModels","summary":"List video generation models","tags":["Video Generation"],"description":"Catalog of video generation models with per-model capability descriptors. `sku_credits` lists the credits per SKU unit.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video model catalog with per-model capability descriptors and Sume billable pricing SKUs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoModelsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/videos":{"post":{"operationId":"createVideoGeneration","summary":"Submit a video generation request","tags":["Video Generation"],"description":"Submits an asynchronous video generation job and returns a polling URL. `model` accepts a catalog id from GET /v1/videos/models, or `auto-` / `sume/auto` / `auto` to let Sume pick; anything else is 404 model_not_found.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"202":{"description":"Video generation job. Bare object, not Sume's { data: ... } envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/videos/{id}":{"get":{"operationId":"getVideoGeneration","summary":"Poll a video generation job","tags":["Video Generation"],"description":"Returns the current job. Poll until `status` is `completed`, then download from `unsigned_urls`.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video generation job. Bare object, not Sume's { data: ... } envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/videos/{id}/content":{"get":{"operationId":"getVideoGenerationContent","summary":"Download a generated video","tags":["Video Generation"],"description":"Redirects to the generated video for a completed job. `index` selects the output when a model returns more than one. A job that terminally failed answers `409 job_failed` with the poll response's public reason, and a canceled job `409 job_canceled`, not the retryable `job_not_completed`.","parameters":[{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"index","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"No video is available to download. `error.code` is `job_not_completed` while the job is still running — that one is retryable, so poll `GET /v1/videos/{id}` and retry. Once the generation has terminally failed, `error.code` is `job_failed` with `retryable: false`, and `error.message` carries the same public reason the poll response reports. A canceled job answers `job_canceled`, also with `retryable: false`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/music-1.0/generate":{"post":{"operationId":"generateMusicV1","summary":"Generate Music 1.0 asset","tags":["Music 1.0"],"description":"Primary Sume Music 1.0 route for text-to-music generation. Provider model ids stay internal; callers use Sume-owned job URLs and the public model id `sume/music-1.0`.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeMusicGenerationRequest"},"examples":{"text_to_music":{"summary":"Text to music","value":{"prompt":"An upbeat indie-pop instrumental with bright acoustic guitar and a catchy chorus energy about starting something new. No vocals, no spoken word.","mode":"async"}},"image_conditioned_music":{"summary":"Image-conditioned music","value":{"prompt":"Cinematic ambient score that matches the mood of the attached still.","image_url":"https://example.com/inputs/moodboard.png","mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"prompt":"A short lo-fi beat for a product demo montage.","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Music generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Music generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/music-1.0/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"prompt\": \"An upbeat indie-pop instrumental with bright acoustic guitar and a catchy chorus energy about starting something new. No vocals, no spoken word.\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/stt-1.0/transcribe":{"post":{"operationId":"transcribeSttV1","summary":"Transcribe audio with STT 1.0","tags":["STT 1.0"],"description":"Primary Sume STT 1.0 route for speech-to-text. Provider model ids stay internal; callers use Sume-owned job URLs and the public model id `sume/stt-1.0`. Completed results expose public-safe `text`, language fields when available, and `words[]` word-level timings (`{ word, start, end }`, seconds from the audio start).\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeSttTranscribeRequest"},"examples":{"transcribe_audio":{"summary":"Transcribe audio","value":{"audio_url":"https://media.sume.com/artifacts/example/clip.m4a","language_code":"ko","duration_seconds":20,"mode":"async"}},"auto_detect_language":{"summary":"Auto-detect language","value":{"audio_url":"https://media.sume.com/artifacts/example/clip.wav","mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"audio_url":"https://media.sume.com/artifacts/example/clip.m4a","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"STT job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"STT job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/stt-1.0/transcribe \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"audio_url\": \"https://media.sume.com/artifacts/example/clip.m4a\",\n  \"language_code\": \"ko\",\n  \"duration_seconds\": 20,\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/rmbg-1.0/remove":{"post":{"operationId":"removeBackgroundRmbgV1","summary":"Remove background with RMBG 1.0","tags":["RMBG 1.0"],"description":"Primary Sume RMBG 1.0 route for background removal. Provider model ids stay internal; callers use Sume-owned job URLs and the public model id `sume/rmbg-1.0`. Completed results expose mirrored PNG artifacts with alpha. When the input already has substantial fully-transparent pixels (typical re-cutout), Sume flattens onto mid-gray `#808080` before provider submission so edges stay clean — still one billed removal; opaque inputs are unchanged.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeRmbgRemoveRequest"},"examples":{"remove_background":{"summary":"Remove background","value":{"image_url":"https://example.com/inputs/portrait.png","mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"image_url":"https://media.sume.com/artifacts/example/input.png","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"RMBG job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"RMBG job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/rmbg-1.0/remove \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"image_url\": \"https://example.com/inputs/portrait.png\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/tts-1.0/source":{"get":{"operationId":"getTtsSourceManifest","summary":"Read accepted TTS source identifiers","tags":["TTS 1.0"],"parameters":[{"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"in":"query","name":"script_revision_id","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["script_revision_id","canonicalization_version","source_sha256","sentence_ids","sentences"],"properties":{"script_revision_id":{"type":"string"},"canonicalization_version":{"type":"string","enum":["nfc-lf-sentence-v1"]},"source_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sentence_ids":{"type":"array","items":{"type":"string"}},"sentences":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["sentence_id","source_block_index","sentence_index","character_count"],"properties":{"sentence_id":{"type":"string"},"source_block_index":{"type":"integer","minimum":0},"sentence_index":{"type":"integer","minimum":0},"character_count":{"type":"integer","minimum":1}}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"acceptTtsSource","summary":"Accept caller-authored TTS source","tags":["TTS 1.0"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["script_texts"],"description":"Caller-only acceptance of script bytes for this thread. Agent credentials cannot create or replace accepted revisions. Supplied LC Format input is bound automatically and does not require this call.","properties":{"script_texts":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string","minLength":1,"maxLength":20000}},"thread_id":{"type":"string","minLength":1,"maxLength":128},"expected_script_revision_id":{"type":"string","nullable":true,"maxLength":128}}}}},"description":"Caller-only acceptance of script bytes for this thread. Agent credentials cannot create or replace accepted revisions. Supplied LC Format input is bound automatically and does not require this call."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["script_revision_id","canonicalization_version","source_sha256","sentence_ids","sentences"],"properties":{"script_revision_id":{"type":"string"},"canonicalization_version":{"type":"string","enum":["nfc-lf-sentence-v1"]},"source_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sentence_ids":{"type":"array","items":{"type":"string"}},"sentences":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["sentence_id","source_block_index","sentence_index","character_count"],"properties":{"sentence_id":{"type":"string"},"source_block_index":{"type":"integer","minimum":0},"sentence_index":{"type":"integer","minimum":0},"character_count":{"type":"integer","minimum":1}}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tts-1.0/source/verify-spine":{"post":{"operationId":"verifyTtsSourceSpine","summary":"Verify complete accepted TTS spine coverage without generation","tags":["TTS 1.0"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["script_revision_id","selected_jobs"],"properties":{"script_revision_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"selected_jobs":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"required":["job_id"],"properties":{"job_id":{"type":"string","minLength":1,"maxLength":128},"sentence_ids":{"type":"array","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}}}}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["script_revision_id","input_integrity","coverage","sentence_ids","receipts"],"properties":{"script_revision_id":{"type":"string"},"input_integrity":{"type":"string","enum":["source_bound"]},"coverage":{"type":"string","enum":["complete"]},"sentence_ids":{"type":"array","items":{"type":"string"}},"receipts":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"Server-owned TTS source-integrity proof. Required for LC acceptance and reuse. Count-only QA or a caller-supplied receipt cannot substitute for this proof.","required":["job_id","script_revision_id","sentence_ids","canonicalization_version","submitted_transcript_sha256","input_integrity"],"properties":{"job_id":{"type":"string"},"script_revision_id":{"type":"string"},"sentence_ids":{"type":"array","items":{"type":"string"}},"canonicalization_version":{"type":"string","enum":["nfc-lf-sentence-v1"]},"submitted_transcript_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"input_integrity":{"type":"string","enum":["source_bound"]}}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tts-1.0/generate":{"post":{"operationId":"generateTtsV1","summary":"Generate speech with TTS 1.0","tags":["TTS 1.0"],"description":"Primary Sume TTS 1.0 route for text-to-speech. Provider credentials stay server-side; callers use Sume-owned job URLs and the public model id `sume/tts-1.0`. Completed results expose mirrored audio artifacts. Phase 1 is async job + poll/webhook (non-streaming).\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTtsGenerateRequest"},"examples":{"generate_speech":{"summary":"Generate speech","value":{"transcript":"Hello from Sume TTS.","voice":{"mode":"id","id":"9f3e2b1c-6a4d-4c8e-9f1a-2b3c4d5e6f70"},"output_format":{"container":"mp3","sample_rate":44100,"bit_rate":128000},"mode":"async"}},"generate_speech_from_avatar":{"summary":"Generate speech using an avatar voice","value":{"transcript":"Hello from this avatar.","avatar_id":"avtr_example","output_format":{"container":"wav","encoding":"pcm_s16le","sample_rate":44100},"mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"transcript":"Hello from Sume TTS.","voice":{"id":"9f3e2b1c-6a4d-4c8e-9f1a-2b3c4d5e6f70"},"mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"TTS job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"TTS job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/tts-1.0/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"transcript\": \"Hello from Sume TTS.\",\n  \"voice\": {\n    \"mode\": \"id\",\n    \"id\": \"9f3e2b1c-6a4d-4c8e-9f1a-2b3c4d5e6f70\"\n  },\n  \"output_format\": {\n    \"container\": \"mp3\",\n    \"sample_rate\": 44100,\n    \"bit_rate\": 128000\n  },\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/tts-router/models":{"get":{"operationId":"listTtsRouterModels","summary":"List TTS Router models","tags":["TTS Router"],"description":"Catalog of explicit pass-through TTS models (model-in-body invoke). Separate from Sume TTS 1.0. v1 is Sonic only; each model lists its credits per 1,000 characters.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"TTS Router catalog listing Sonic pass-through models with the TTS 1.0 list×1.10 character book.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsRouterModelsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tts-router/models/{model_id}":{"get":{"operationId":"getTtsRouterModel","summary":"Get TTS Router model","tags":["TTS Router"],"description":"Return one TTS Router catalog model by id. Returns 404 when the model id is not in the seed catalog.","parameters":[{"schema":{"type":"string"},"in":"path","name":"model_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One TTS Router catalog model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsRouterModelResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tts-router/voices":{"get":{"operationId":"listTtsRouterVoices","summary":"List TTS Router voices","tags":["TTS Router"],"description":"Voices a TTS Router model family can speak with, read live and cached for ten minutes. family=sonic lists the public Sonic voice library (use with sonic-* models); family=eleven lists ElevenLabs voices (use with eleven-* models) — the premade voices when no ElevenLabs account is connected (source: premade); family=seed_audio, qwen, minimax and seed_speech list the fixed preset voices of seed-audio-1.0, qwen-audio-3.0-tts, minimax-speech-2.8-hd and seed-speech (source: preset). A catalog model's voice_family names its list. Your own cloned voices stay in the Voices library (voi_* ids, sonic-* models).","parameters":[{"schema":{"type":"string","enum":["sonic","eleven","seed_audio","qwen","minimax","seed_speech"]},"in":"query","name":"family","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Voices one TTS Router model family can speak with (sonic or eleven), with language, gender, accent and preview URL where the voice library gives them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsRouterVoicesResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tts-router/generate":{"post":{"operationId":"generateTtsRouter","summary":"Generate via TTS Router","tags":["TTS Router"],"description":"Explicit pass-through text-to-speech. Requires `model` from GET /v1/tts-router/models. job.model equals the requested routable id. Voice selection, transcript rules, and billing match TTS 1.0; the engine picker is the only difference between the surfaces.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTtsRouterGenerateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/music-router/models":{"get":{"operationId":"listMusicRouterModels","summary":"List Music Router models","tags":["Music Router"],"description":"Catalog of Music Router models: `sume/music-auto` (Sume picks the engine — Lyria 3.5 today) plus explicit Lyria pass-through ids. Every row is the fixed Music price. Music 1.0 requests resolve through this router.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Music Router catalog: sume/music-auto plus the pass-through engines (Lyria, ElevenLabs, MiniMax, Stable Audio, ACE-Step), each with its own price in credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MusicRouterModelsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/music-router/models/{model_id}":{"get":{"operationId":"getMusicRouterModel","summary":"Get Music Router model","tags":["Music Router"],"description":"Return one Music Router catalog model by id. Returns 404 when the model id is not in the catalog.","parameters":[{"schema":{"type":"string"},"in":"path","name":"model_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Music Router catalog model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MusicRouterModelResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/music-router/generate":{"post":{"operationId":"generateMusicRouter","summary":"Generate via Music Router","tags":["Music Router"],"description":"Music generation through the Music Router. `model` is optional: omitted or `sume/music-auto` lets Sume pick the engine (Lyria 3.5 today); explicit catalog ids from GET /v1/music-router/models pass through. job.model echoes the requested routable id; job.request.routed_model names the catalog engine that ran. Same prompt / image_url rules and fixed price as Music 1.0.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeMusicRouterGenerateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/video-upscale-1.0/upscale":{"post":{"operationId":"upscaleVideoV1","summary":"Upscale a video with Video Upscale 1.0","tags":["Video Upscale 1.0"],"description":"Primary Sume Video Upscale 1.0 route. Provider model ids stay internal; callers use Sume-owned job URLs and the public model id `sume/video-upscale-1.0`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoUpscaleRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/timeline-1.0/plan":{"post":{"operationId":"planTimelineV1","summary":"Validate a Timeline 1.0 document and return a compile plan","tags":["Timeline 1.0"],"description":"Unbilled preflight (VEAC check/plan analogue). Runs schema + admit bounds + the pure filtergraph compiler and returns duration, billable minutes, cost estimate, and a filtergraph summary. Does not fetch media, create a job, or reserve credits. Cannot predict short-source downgrade warnings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTimelineRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Unbilled timeline plan/check result (no job, no reserve).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTimelinePlan"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/timeline-1.0/render":{"post":{"operationId":"renderTimelineV1","summary":"Render a declarative long-form Timeline 1.0 video","tags":["Timeline 1.0"],"description":"Primary Sume Timeline 1.0 route. Accepts a declarative timeline document (audio spine + video slots + transitions). Only Sume's compiler produces ffmpeg args — callers cannot supply filtergraphs, codecs, or shell fragments. Renders on the Railway worker ffmpeg runtime.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTimelineRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/timeline-1.0/audio":{"post":{"operationId":"createTimelineV1Audio","summary":"Combine or split Timeline 1.0 audio into Sume-hosted files","tags":["Timeline 1.0"],"description":"Joins Sume-hosted audio into one gapless file (operation concat) or slices one file into ranges (operation split), and returns durable media.sume.com URLs plus timings. The join is sample-domain — no re-synthesis and no silence at the seams — so a voiceover packed as per-sentence slices can be merged into one file that drives Avatar 1.0 image-to-video, or re-used across renders. Callers cannot supply filtergraphs, codecs, or shell fragments. Runs on the same worker ffmpeg runtime as the render. When the joined spine is only needed inside one render, use audio.parts[] on POST /v1/timeline-1.0/render instead and skip this job.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTimelineAudioRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/timeline-1.0/compose":{"post":{"operationId":"createTimelineV1Compose","summary":"Compose a still and a video into one frame","tags":["Timeline 1.0"],"description":"Composes one Sume-hosted still and one Sume-hosted video into a single MP4 on media.sume.com, so two sources are on screen at the same time. mode stack splits the frame and tiles the two layers into it — the 반배너 (half-banner) shape is a horizontal split with the banner image on top and the avatar video underneath. mode overlay floats the still over a full-frame video. The output length always comes from the video layer; the still is held for the whole clip and can never lengthen it. The composed clip is a normal slot for POST /v1/timeline-1.0/render — compose builds one shot, the render assembles the show. Sequential image-then-video is not a mode here: adjacent video[] slots on the render already express it. Callers cannot supply filtergraphs, codecs, or shell fragments. Runs on the same worker ffmpeg runtime as the render.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTimelineComposeRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-trim":{"post":{"operationId":"createVideoTrimV1","summary":"Cut a [start, end) range out of one hosted clip","tags":["Video Trim 1.0"],"description":"Cuts a range out of one Sume-hosted clip and returns one durable media.sume.com MP4 artifact holding only that range; the source is untouched. The program is the whole surface: start plus exactly one of end / duration, precision exact (frame-accurate re-encode, optional output conform) or keyframe (stream copy, may start a GOP early and reports actual_start_seconds), audio keep|drop. The server compiles the ffmpeg on the worker media runtime, so callers never supply -i, argv, codecs, presets, crf, filtergraphs or shell fragments — any such field is 400 ffmpeg_fields_rejected. This is material preparation, not placement: sequencing, transitions and the audio spine stay on POST /v1/timeline-1.0/render, and the trimmed MP4 drops into that route's video[] slot with source_in 0. Max 1800 seconds of source and 900 seconds of output. Reserved at 6.4 credits per job, captured at the pass's own compute, never above the reservation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoTrimRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/video-trim-1.0/runs":{"post":{"operationId":"runSumeVideoTrimV1Model","summary":"Run Sume Video trim 1.0","tags":["Models"],"description":"Canonical Sume Video trim 1.0 model-run endpoint. Accepts the same range program body as POST /v1/video-trim without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoTrimRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/audio-detach":{"post":{"operationId":"createAudioDetachV1","summary":"Extract the audio track of one hosted video","tags":["Audio Detach 1.0"],"description":"Demuxes the audio track of one Sume-hosted video into one durable media.sume.com audio artifact — sample-exact wav by default (what POST /v1/timeline-1.0/render audio.url, POST /v1/timeline-1.0/audio and speech-to-text want) or mp3; the video is untouched. Optional single range, channels source|mono, sample_rate 16000|44100|48000. A source with no audio track fails detach_source_has_no_audio. The server compiles the ffmpeg on the worker media runtime, so callers never supply -i, argv, codecs or filters — any such field is 400 ffmpeg_fields_rejected. Max 1800 seconds of source and 900 seconds of output. Flat 6.4 credits per job.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAudioDetachRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/audio-detach-1.0/runs":{"post":{"operationId":"runSumeAudioDetachV1Model","summary":"Run Sume Audio detach 1.0","tags":["Models"],"description":"Canonical Sume Audio detach 1.0 model-run endpoint. Accepts the same body as POST /v1/audio-detach without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAudioDetachRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/voice-change":{"post":{"operationId":"createVoiceChangeV1","summary":"Speak one hosted recording again in an ElevenLabs voice","tags":["Voice Change 1.0"],"description":"One durable media.sume.com recording (1-300 s, `duration_seconds` as measured) spoken again in an ElevenLabs voice (`voice.id`, a /v1/tts-router/voices?family=eleven id). A video comes back as the same video with the new voice (`video_url`, plus the voice alone as `audio_url`); a recording comes back as audio. Reserved at 18.75 credits per source minute (by the second) and captured as reserved; a file longer than declared fails and refunds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/voice-change-1.0/runs":{"post":{"operationId":"runSumeVoiceChangeV1Model","summary":"Run Sume Voice change 1.0","tags":["Models"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/dubbing":{"post":{"operationId":"createDubbingV1","summary":"Dub one hosted clip into another language","tags":["Dubbing 1.0"],"description":"One durable media.sume.com clip — `video_url` or `audio_url`, 1-300 s, `duration_seconds` as measured — dubbed into `target_lang`. Reserved at 37.5 credits per started source minute and captured as reserved; a file longer than declared fails and refunds. `lip_sync: true` (video_url only, 2-300 s) translates, re-voices each speaker and syncs their lips in one pass, reserved at 6.88 credits per source second instead; `num_speakers` is not taken with it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/dubbing-1.0/runs":{"post":{"operationId":"runSumeDubbingV1Model","summary":"Run Sume Dubbing 1.0","tags":["Models"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-filter/check":{"post":{"operationId":"checkVideoFilterV1","summary":"Check a video filter program without encoding (unbilled)","tags":["Video Filter 1.0"],"description":"Unbilled preflight — the HyperFrames-lint half of the video filter. Runs the same schema, program contract (op whitelist; filtergraph allowlist, labels and alphabet) and Sume-host / HEAD source preflight as POST /v1/video-filter, and returns them as diagnostics instead of a 400. Does not create a job, reserve credits, boot a box, or touch the encoder; program.filters is the compiled filter list (names only, no argv). A program that passes here can still fail on the box for a bad expression, memory or time — that comes back as a structured job error to fix and resubmit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoFilterCheckRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Unbilled video filter program check (no job, no reserve, no encode).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoFilterCheck"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-filter":{"post":{"operationId":"createVideoFilterV1","summary":"Apply a validated ops[] program (v1: dim) to one hosted clip","tags":["Video Filter 1.0"],"description":"Applies a small validated ops[] program to one Sume-hosted clip and returns one durable media.sume.com MP4 artifact. The program is the whole surface: the server compiles ops[] into its own encoder graph on the worker ffmpeg runtime, so callers never supply filtergraphs, ffmpeg arguments, codecs, presets, crf or shell fragments — any such field is 400 ffmpeg_fields_rejected. v1 supports dim only (amount in (0, 1] multiplies luma; 0.45 is darker, 1 is unchanged; 0 and >1 are rejected). Output inherits the source geometry, frame rate and audio, so the result drops back into the same POST /v1/timeline-1.0/render slot. This is a whole-clip pixel pass — assembly stays on the render, and a dark plate under caption text is HTML on the caption composer. Max 300 seconds of source. Reserved at 6.4 credits per job, captured at the pass's own compute, never above the reservation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoFilterRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/video-filter-1.0/runs":{"post":{"operationId":"runSumeVideoFilterV1Model","summary":"Run Sume Video filter 1.0","tags":["Models"],"description":"Canonical Sume Video filter 1.0 model-run endpoint. Accepts the same ops[] program body as POST /v1/video-filter without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoFilterRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/veed/fabric-1.0":{"post":{"operationId":"createVeedFabric10","summary":"Create VEED Fabric 1.0 clip","tags":["VEED Fabric 1.0"],"description":"Primary VEED Fabric 1.0 route. Turns a still image (or ready avatar still) plus Sume-hosted audio into a talking clip. Provider queue ids stay internal; callers use Sume-owned job URLs and the public model id `veed/fabric-1.0`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAvatarImageToVideoRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/avatar-1.0/image-to-video":{"post":{"operationId":"createAvatarV1ImageToVideo","summary":"Create VEED Fabric 1.0 clip (deprecated alias)","tags":["Avatar 1.0"],"description":"Deprecated / retiring. Compatibility alias; still supported for existing integrations. Use `POST /v1/veed/fabric-1.0` (public model id `veed/fabric-1.0`) with the same request body: `audio_url`, `duration_seconds`, and exactly one visual source. Prefer `image_url` of the generated, inspected posed still; use `avatar_handle` instead only if the user named that avatar (XOR, never both).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAvatarImageToVideoRequest"}}}},"deprecated":true,"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/avatar-1.0/fabric":{"post":{"operationId":"createAvatarV1Fabric","summary":"Create Avatar 1.0 fabric clip (experimental)","tags":["Avatar 1.0"],"description":"EXPERIMENTAL test route. Takes the same body as `POST /v1/avatar-1.0/image-to-video` but renders through a different backend so the two can be compared on identical inputs. Differences: `duration_seconds` is capped at 15 and `speed_tier` is ignored. Provider model ids stay internal; callers use Sume-owned job URLs and the public model id `sume/avatar-1.0/fabric`. This surface is test-only and the model id will change before general availability — do not build production integrations on it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAvatarFabricRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/kling/3.0/motion-control":{"post":{"operationId":"createKlingMotionControl","summary":"Create Kling 3.0 Motion Control clip","tags":["Kling 3.0 Motion Control"],"description":"Primary Kling 3.0 Motion Control route. Animates a still image (or ready avatar still) with the motion of a caller-supplied driving video. Output length follows the driving video. Provider queue ids stay internal; callers use Sume-owned job URLs and the public model id `kling/3.0/motion-control`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeKlingMotionControlRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/avatar-1.0/motion-control":{"post":{"operationId":"createAvatarV1MotionControl","summary":"Create Kling 3.0 Motion Control clip (face-control path)","tags":["Avatar 1.0"],"description":"Face-control alias of `POST /v1/kling/3.0/motion-control`. Same body; created jobs store the public model id `kling/3.0/motion-control`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeKlingMotionControlRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/trending-videos/search":{"post":{"operationId":"searchTrendingVideos","summary":"Search TikTok trending video metadata","tags":["Trending Videos"],"description":"Searches TikTok trend candidates and returns ranked public metadata only. Each accepted search uses 7 credits, including `summary_mode: metadata`. The endpoint does not download, mirror, or expose raw TikTok CDN media URLs. The rebuilt browse feed, optional query, and higher limit are on for the development API (api.dev). Production stays on the legacy contract until the rebuild is explicitly enabled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingVideosSearchRequest"},"examples":{"known_saas_profile":{"summary":"Search a known SaaS profile","value":{"platform":"tiktok","query":"creatify","limit":10,"summary_mode":"none"}},"current_trending_browse":{"summary":"Browse the current trending feed (on for api.dev; production stays on the legacy contract until explicitly enabled)","value":{"platform":"tiktok","limit":48,"summary_mode":"metadata"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Ranked TikTok trending video metadata for the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingVideosSearchResponse"},"examples":{"ranked_tiktok_metadata":{"summary":"Ranked TikTok metadata","value":{"data":{"platform":"tiktok","query":"creatify","fetched_at":"2026-07-08T00:00:00.000Z","params":{"platform":"tiktok","query":"creatify","mode":"search","profile":"creatify","region":null,"window":"last-3-months","limit":10,"search_queries":["creatify","creatify ai","creatify.ai","creatifyai"],"sort_modes":["most-liked","relevance"],"summary_mode":"none","download":false,"download_limit":0,"min_relevance":0.75,"min_views":10000,"cached":false},"count":1,"videos":[{"platform":"tiktok","rank":1,"id":"7350000000000000001","url":"https://www.tiktok.com/@creatify/video/7350000000000000001","cover_url":"https://p16-sign.tiktokcdn.com/cover.jpeg","description":"Creatify AI UGC ad breakdown #creatify","content_type":"video","created_at":"2026-07-01T00:00:00.000Z","region":"US","author":{"handle":"creatify","nickname":"Creatify","verified":true},"metrics":{"views":70000,"likes":7000,"comments":200,"shares":500,"saves":350,"engagement_rate":0.115,"bayesian_like_rate":0.095,"bayesian_comment_rate":0.002875,"bayesian_share_save_rate":0.012375},"relevance":{"score":1,"reason":"author match: creatify; context: ugc, ad, ai"},"scores":{"viral_score":31.25,"relevance_score":1,"base_score":40.06,"components":{"views_score":60.25,"velocity_score":34.1,"like_score":28.4,"comment_score":8.2,"share_save_score":18.5,"recency_score":50.7,"multi_surface_score":6.24,"view_confidence":0.78,"recency_damping":1,"creator_diversity_penalty":1}},"source":{"surfaces":["keyword","top"],"sort_modes":["most-liked","relevance"],"search_queries":["creatify","creatify ai"]},"summary":null}],"warnings":[],"usage":{"status":"captured","reserved_credits":7,"captured_credits":7,"refunded_credits":0,"released_credits":0,"final":true,"updated_at":"2026-07-08T00:00:01.000Z"}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/trending-research":{"post":{"operationId":"searchTrendingResearch","summary":"Search trending Instagram and TikTok videos for a niche","tags":["Trending Videos"],"description":"Pulls a research list of public trending short videos from Instagram (Meta) and TikTok. Niche comes from a typed query or Brand DNA / business category. YouTube is unsupported. Each accepted search uses 7 credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingResearchSearchRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Ranked Instagram + TikTok research list for a typed niche or Brand DNA category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingResearchSearchResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/influencer-search":{"post":{"operationId":"searchInfluencers","summary":"Search Instagram, TikTok, and YouTube creators for a brief","tags":["Influencer Search"],"description":"Ranked cold-discovery shortlist from a niche or natural-language query. Calls `@sume-com/influencer-discovery` in-process. Unset Modash keys return DEV fixtures (success). Unbilled — no Sume SKU. Not the platform avatar catalog under `/api/influencers`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InfluencerSearchRequest"},"examples":{"niche_brief":{"summary":"Niche + filters","value":{"niche":"k-beauty","platforms":["ig","tt"],"geo":"KR","language":"ko","follower_min":20000,"follower_max":400000,"engagement_min":0.03,"limit":12}},"natural_language":{"summary":"Natural-language query","value":{"query":"glass skin creators in seoul","platforms":["ig","tt"],"limit":8}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Ranked Instagram / TikTok / YouTube creator shortlist. DEV without a Modash key returns fixtures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InfluencerSearchResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/me":{"get":{"operationId":"getAuthenticatedAccount","summary":"Get authenticated API key account","tags":["Account"],"description":"Verifies the provided developer API key and returns non-secret account and key metadata.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Non-secret account and API-key metadata for the authenticated key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhooks/signing-secret":{"get":{"operationId":"getWebhookSigningSecret","summary":"Get webhook signing secret","tags":["Account"],"description":"Returns the signing secret Sume signs this caller's webhooks with, derived for the key's workspace (or account, for a personal key). One secret covers both generation-job (`job.*`) and run (`format.run.terminal`) webhooks. Pair it with `verifyWebhook` from `@sume-com/client`. The `fingerprint` matches `x-sume-webhook-secret-fingerprint` on deliveries, so support can confirm both sides hold the same secret without either quoting it.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"The authenticated caller's webhook signing secret, derived for their workspace or account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSigningSecretResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not carry `account:read`. Stable `error.code` value: `insufficient_scope`. Every self-service key minted from the dashboard carries it; a key that does not must be replaced, since scopes cannot be added to an existing key.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhooks/signing-secret/rotate":{"post":{"operationId":"rotateWebhookSigningSecret","summary":"Rotate webhook signing secret","tags":["Account"],"description":"Issues a new signing secret for this caller's workspace (or account, for a personal key) and returns it. The previous secret keeps verifying for 24 hours: during that window every delivery carries a signature from both secrets in `x-sume-webhook-signature`, comma-separated and newest first, so you can redeploy your verifier without dropping deliveries. Use `verifyWebhook` from `@sume-com/client` 0.3.0 or later, which accepts a multi-signature header; an older verifier that compares the header for equality will fail during the window. Rotating again while a window is open replaces it — the secret two rotations back stops verifying immediately.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"A freshly rotated webhook signing secret, with the overlap window during which the previous one still verifies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSigningSecretRotateResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not carry `account:read`. Stable `error.code` value: `insufficient_scope`. Every self-service key minted from the dashboard carries it; a key that does not must be replaced, since scopes cannot be added to an existing key.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhooks/test-deliveries":{"post":{"operationId":"createWebhookTestDelivery","summary":"Send test webhook","tags":["Account"],"description":"POSTs a dummy signed `webhook.test` event to a caller-supplied public HTTPS URL so a receiver can prove URL + secret + 2xx without a real job or Format run. Requires `account:write`. This is not a redeliver of a real call — use `POST /v1/jobs/{id}/webhook/redeliver` or `POST /v1/format-runs/{run_id}/webhook/redeliver` for that.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestDeliveryRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Result of POSTing a dummy `webhook.test` event to a caller-supplied HTTPS URL. This is not a job or Format run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestDeliveryResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not carry `account:write`. Stable `error.code` value: `insufficient_scope`. Missing scopes never answer `404`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/balance":{"get":{"operationId":"getApiBalance","summary":"Get API balance","tags":["Billing"],"description":"Returns the authenticated workspace's current credits balance (whole credits, rounded down) and the credits expiring next. Missing balance rows are represented as an explicit zero balance.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Workspace-scoped credits balance for the authenticated key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/usage":{"get":{"operationId":"listApiUsage","summary":"List API usage","tags":["Billing"],"description":"Lists the newest usage ledger rows for the authenticated workspace. Rows expose Sume job/request ids and their credits only; provider internals and idempotency keys are omitted.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Newest rows returned. With a scope filter the summary always folds every row of the scope; limit only caps the rows listed."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"thread_id","required":false,"description":"Sum every ledger row this Studio Agent thread caused — its turns, sidecars, Browser sessions and generation jobs (script_run children included) — and list them newest first. A thread-bound credential may name only its own thread."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"run_id","required":false,"description":"Sum a Format / Action / Agent run (arun_…): its generation jobs plus the run thread's own turn rows. `summary.cap` is the generation-cap accounting the run receipt prints; `summary.debited_credits` is what the wallet deducted."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"job_id","required":false,"description":"One generation job's ledger row, or an agent turn's job id: the turn's own row plus every job it commissioned (script_run children included)."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Recent usage ledger rows for the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs":{"get":{"operationId":"listApiJobs","summary":"List API jobs","tags":["Jobs"],"description":"Lists read-only job status records scoped to the authenticated developer workspace. Provider-backed jobs expose Sume-owned model and status fields only. A job is readable by the key's owner, or by a Studio Agent turn bound to the thread the job belongs to: `scope` defaults to `thread` for a thread-bound credential, which lists every job stamped for that thread whoever created it (an API Format run's jobs included), and to `workspace` for an ordinary API key, which lists the key owner's own jobs. An interactive turn may pass `scope=workspace` to list its own jobs across the workspace; an unattended run may not, and gets `job_scope_forbidden`. `run_id` narrows further to one automation run without ever widening past the thread. `thread_id`, `type` and `status` narrow the page further; `thread_id` may only ever name the caller's own thread, so it never widens a bound credential. Results are newest-first and capped at 100 per page: when `data.next_cursor` is present, pass it back as `starting_after` to read the next page. An unrecognized query parameter is a `400 unknown_parameter` rather than a silently unfiltered page. Newest-first is not your submission order once a wave retries, so do not read identity off array position: each row carries the `idempotency_key` it was created with, and that is the column to join your own labels on.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["thread","workspace"]},"in":"query","name":"scope","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"run_id","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"thread_id","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"starting_after","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Recent jobs for the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobsListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is bound to one Studio Agent thread and asked for `scope=workspace` while an automation run was in flight. Stable `error.code` value: `job_scope_forbidden`. An unattended run may only see the jobs its own thread created; drop the `scope` parameter to read them.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}":{"get":{"operationId":"getApiJob","summary":"Get API job","tags":["Jobs"],"description":"Returns one read-only job status record from the authenticated developer workspace. Readable by the key's owner, or by a Studio Agent turn bound to the thread the job belongs to; jobs in other workspaces, and other members' jobs in other threads, are 404.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One job record scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}/status":{"get":{"operationId":"getApiJobStatus","summary":"Get API job queue status","tags":["Jobs"],"description":"Returns queue-friendly status metadata for SDKs and CLI clients. The status/result URLs follow the same request id returned by submit endpoints. Readable by the key's owner, or by a Studio Agent turn bound to the thread the job belongs to; jobs in other workspaces, and other members' jobs in other threads, are 404.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queue-friendly status metadata for polling clients.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}/result":{"get":{"operationId":"getApiJobResult","summary":"Get API job result","tags":["Jobs"],"description":"Returns a completed job result. A queued or processing job answers `409 job_not_completed` with the current status in details; it is retryable, so poll `status_url` and read again once the job completes. A failed job answers `409 job_failed` with the failure's public reason as the message, and a canceled job `409 job_canceled`; neither is retryable. Readable by the key's owner, or by a Studio Agent turn bound to the thread the job belongs to; jobs in other workspaces, and other members' jobs in other threads, are 404.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Completed job result payload with public-safe artifacts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResultResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"No result payload is available. Stable `error.code` values: `job_not_completed` while the job is queued or processing (`retryable: true`, `next_action: poll_status`, `details.status` names the state), `job_failed` once it failed (`retryable: false`, `next_action: inspect_events`, and `message` carries the same public reason `GET /v1/jobs/{id}/status` reports), and `job_canceled` once it was canceled (`retryable: false`). Only `job_not_completed` is worth polling.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}/cancel":{"post":{"operationId":"cancelApiJob","summary":"Cancel API job","tags":["Jobs"],"description":"Durably cancels a Sume job only before generation work has started. Once any external generation task has begun, cancellation is rejected so usage settlement cannot refund work already submitted for generation.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Canceled job envelope for a job canceled before generation started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCancelResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The job cannot be canceled because it is terminal or generation work has already started. Already-canceled jobs return a successful idempotent response.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}/webhook/redeliver":{"post":{"operationId":"redeliverApiJobWebhook","summary":"Redeliver job webhook","tags":["Jobs"],"description":"Re-POSTs this job's real terminal payload (`job.completed` / `job.failed` / `job.canceled`) with a fresh timestamp and `sume-v1` signature. Requires `jobs:write`. Works after automatic attempts are exhausted. Does not consume one of the automatic 10 retries. 409 if the job is still running or was created without a webhook_url. Tenancy hide: a job you cannot see is `404`.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Updated job `webhook_delivery` after a manual redeliver of that call's real terminal payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRedeliverResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not carry `jobs:write`. Stable `error.code` value: `insufficient_scope`. Missing scopes never answer `404`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The call cannot be redelivered. Stable `error.code` values: `webhook_not_configured` when the job or run was created without a webhook_url, `job_not_terminal` / `run_not_terminal` when it is still running.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}/events":{"get":{"operationId":"listApiJobEvents","summary":"List API job events","tags":["Jobs"],"description":"Returns a sanitized job lifecycle timeline for debugging. The timeline derives from Sume job state, terminal event outbox rows, and webhook delivery metadata; raw provider URLs, provider task ids, callback signatures, and secrets are omitted. Readable by the key's owner, or by a Studio Agent turn bound to the thread the job belongs to; jobs in other workspaces, and other members' jobs in other threads, are 404. A reader who did not create the job gets no webhook host or delivery error text.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sanitized job lifecycle and delivery timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEventsResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-1.0/generate":{"post":{"operationId":"generateAvatarV1","summary":"Generate Avatar 1.0 avatar","tags":["Avatar 1.0"],"description":"Primary Sume Avatar 1.0 route for creating a reusable avatar identity. This route uses the launch body shape with `avatar_handle` and `input`, while preserving provider-neutral job, resource, billing, and callback behavior.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarModelRunRequest"},"examples":{"prompt_avatar":{"summary":"Create an avatar from a prompt","value":{"avatar_handle":"mina","input":{"type":"prompt","prompt":"A friendly Korean presenter"},"mode":"async"}},"photo_avatar":{"summary":"Create an avatar from a photo URL","value":{"avatar_handle":"uploaded_presenter","input":{"type":"photo","image_url":"https://example.com/inputs/presenter.png"},"mode":"sync","wait_timeout_seconds":20}},"props_avatar":{"summary":"Create an avatar from public props","value":{"avatar_handle":"yuna_creator","input":{"type":"props","ethnicity":"Asian","sex":"female","age":25},"mode":"async"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume-owned model-run submission envelope. Use the returned Sume job URLs for lifecycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRunResponse"},"examples":{"async_queued":{"summary":"Avatar workflow accepted","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"sync","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Sume-owned model-run submission envelope. Use the returned Sume job URLs for lifecycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRunResponse"},"examples":{"async_queued":{"summary":"Avatar workflow accepted","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"sync","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar model-run submit conflicts. Possible stable `error.code` values: `avatar_handle_taken`, `avatar_handle_reserved`, `idempotency_conflict`, or `avatar_not_ready` when creating a video from an existing avatar that is not ready.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_handle_taken":{"summary":"Handle already exists","value":{"error":{"code":"avatar_handle_taken","message":"Avatar handle @studio_presenter is already in use.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_handle_taken","next_action":"fix_input","details":{"handle":"studio_presenter","avatar_id":"avtr_0123456789abcdef"}}}},"avatar_handle_reserved":{"summary":"Handle prefix is reserved","value":{"error":{"code":"avatar_handle_reserved","message":"@sume_presenter uses the reserved sume_ avatar handle prefix. Choose a non-reserved handle for user-created avatars.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_handle_reserved","next_action":"fix_input","details":{"handle":"sume_presenter","reserved_prefix":"sume_","reserved_for":"system_avatars"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/avatar-1.0/generate \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"mina\",\n  \"input\": {\n    \"type\": \"prompt\",\n    \"prompt\": \"A friendly Korean presenter\"\n  },\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/avatar-1.0/avatars":{"get":{"operationId":"listAvatarV1Avatars","summary":"List Avatar 1.0 avatars","tags":["Avatar 1.0"],"description":"Primary Avatar 1.0 route for listing reusable avatar identities. Response shape matches the compatibility `/v1/avatars` route.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["queued","processing","completed","failed","canceled","ready"]},"in":"query","name":"status","required":false,"description":"`ready` is accepted as a resource-friendly alias for completed jobs."},{"schema":{"type":"string"},"in":"query","name":"handle","required":false,"description":"Optional avatar handle filter. Accepts the stored handle with or without @."},{"schema":{"type":"string","enum":["workspace"]},"in":"query","name":"scope","required":false,"description":"`workspace` lists only this workspace's own avatars, without the public catalog."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar resource summaries for the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-1.0/avatars/{id}":{"get":{"operationId":"getAvatarV1Avatar","summary":"Get Avatar 1.0 avatar","tags":["Avatar 1.0"],"description":"Primary Avatar 1.0 route for reading one reusable avatar identity. Response shape matches the compatibility `/v1/avatars/:id` route.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-1.0/talking-video":{"post":{"operationId":"createAvatarV1TalkingVideo","summary":"Create Avatar 1.0 talking video","tags":["Avatar 1.0"],"description":"Primary Avatar 1.0 route for creating a script-driven talking avatar video from a ready avatar handle. Provider implementation ids stay internal; clients use the returned job URLs for async lifecycle.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoCreateRequest"},"examples":{"avatar_video_model_run":{"summary":"Run Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","script":"Share a quick product benefit in one concise sentence.","product_image":"https://example.com/inputs/product.png","scene":{"type":"prompt","prompt":"Bright product demo set"},"quality":"max","aspect_ratio":"9:16","mode":"async"}},"productless_avatar_video_model_run":{"summary":"Run productless Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","script":"Share a quick update in one concise sentence.","quality":"plus","mode":"sync","wait_timeout_seconds":20}},"multi_scene_avatar_video_model_run":{"summary":"Run multi-scene Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","aspect_ratio":"9:16","quality":"plus","mode":"async","video_inputs":[{"id":"hook","voice":{"type":"text","script":"Wait, this turned one selfie into a whole video?","duration":3},"background":{"type":"prompt","prompt":"Casual bedroom or couch background, selfie-camera framing, native UGC lighting."}},{"id":"demo","voice":{"type":"text","input_text":"You pick a template, drop in your photo, and it builds the clip around you.","duration":5},"background":{"type":"prompt","prompt":"Casual bedroom or couch background, selfie-camera framing, native UGC lighting."}}]}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"202":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar-video submit conflicts. Possible stable `error.code` values: `avatar_not_ready` when the referenced avatar is not ready, or `idempotency_conflict` when the Idempotency-Key was reused for a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_not_ready":{"summary":"Referenced avatar is not video-ready","value":{"error":{"code":"avatar_not_ready","message":"Avatar is not ready for video generation.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_not_ready","next_action":"inspect_events","details":{"avatar_id":"avtr_0123456789abcdef","status":"processing"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"sume_clawra\",\n  \"script\": \"Share a quick product benefit in one concise sentence.\",\n  \"product_image\": \"https://example.com/inputs/product.png\",\n  \"scene\": {\n    \"type\": \"prompt\",\n    \"prompt\": \"Bright product demo set\"\n  },\n  \"quality\": \"max\",\n  \"aspect_ratio\": \"9:16\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/avatar-video-previews":{"post":{"operationId":"createAvatarVideoPreview","summary":"Create avatar-video preview","tags":["Avatar Video Previews"],"description":"Creates the Avatar Video first-frame preview stage. For multi-scene `video_inputs` with a shared scene, the preview generates one first frame and pose-anchored continuations for later scenes (same continuity as full Avatar Video). The returned preview can later be used with generate-video to start the normal final video workflow.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewCreateRequest"},"examples":{"multi_scene_preview":{"summary":"Create a multi-scene Avatar Video preview","value":{"avatar_handle":"sume_clawra","aspect_ratio":"9:16","quality":"plus","mode":"async","video_inputs":[{"id":"hook","voice":{"type":"text","script":"Wait, this turned one selfie into a whole video?","duration":3},"background":{"type":"prompt","prompt":"Casual bedroom background, selfie-camera framing, native UGC lighting."}}]}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued avatar-video preview resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video preview queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-1.0/talking-video","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_preview_id":"avp_0123456789abcdef","preview":{"id":"avp_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"202":{"description":"Queued avatar-video preview resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video preview queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-1.0/talking-video","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_preview_id":"avp_0123456789abcdef","preview":{"id":"avp_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar-video submit conflicts. Possible stable `error.code` values: `avatar_not_ready` when the referenced avatar is not ready, or `idempotency_conflict` when the Idempotency-Key was reused for a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_not_ready":{"summary":"Referenced avatar is not video-ready","value":{"error":{"code":"avatar_not_ready","message":"Avatar is not ready for video generation.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_not_ready","next_action":"inspect_events","details":{"avatar_id":"avtr_0123456789abcdef","status":"processing"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/avatar-video-previews \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"sume_clawra\",\n  \"aspect_ratio\": \"9:16\",\n  \"quality\": \"plus\",\n  \"mode\": \"async\",\n  \"video_inputs\": [\n    {\n      \"id\": \"hook\",\n      \"voice\": {\n        \"type\": \"text\",\n        \"script\": \"Wait, this turned one selfie into a whole video?\",\n        \"duration\": 3\n      },\n      \"background\": {\n        \"type\": \"prompt\",\n        \"prompt\": \"Casual bedroom background, selfie-camera framing, native UGC lighting.\"\n      }\n    }\n  ]\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/avatar-video-previews/{id}":{"get":{"operationId":"getAvatarVideoPreview","summary":"Get avatar-video preview","tags":["Avatar Video Previews"],"description":"Returns a scoped avatar-video preview resource with public-safe first-frame metadata. Multi-scene previews expose one `scene_previews[]` entry per input scene.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar-video preview resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-video-previews/{id}/generate-video":{"post":{"operationId":"generateAvatarVideoFromPreview","summary":"Generate avatar video from preview","tags":["Avatar Video Previews"],"description":"Starts the normal Avatar Video generation workflow from an approved preview and reuses the preview first frame when available. Optional body `{ quality }` overrides the final render tier without creating a new preview; empty/`{}` body keeps the stored preview quality.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewGenerateVideoRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"}}}},"202":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar-video submit conflicts. Possible stable `error.code` values: `avatar_not_ready` when the referenced avatar is not ready, or `idempotency_conflict` when the Idempotency-Key was reused for a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-video-previews/{id}/regenerate":{"post":{"operationId":"regenerateAvatarVideoPreview","summary":"Regenerate avatar-video preview","tags":["Avatar Video Previews"],"description":"Regenerates first-frame stills for an existing Avatar Video preview. Reuses the stored preview request and returns the same avatar_video_preview_id with a new preview_only job. Preview must be completed, failed, or canceled (not queued/processing).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewRegenerateRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued avatar-video preview resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewSubmitResponse"}}}},"202":{"description":"Queued avatar-video preview resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoPreviewSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar-video submit conflicts. Possible stable `error.code` values: `avatar_not_ready` when the referenced avatar is not ready, or `idempotency_conflict` when the Idempotency-Key was reused for a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/image-1.0/runs":{"post":{"operationId":"runSumeImageV1Model","summary":"Run Sume Image 1.0 (retiring soon)","tags":["Models"],"description":"Retiring soon. Compatibility alias for Image Router Auto (POST /v1/images with sume/auto). Accepts provider-hidden public image generation inputs without a `model` field and submits a Sume-owned image generation job. Optional `transparency: true` chains Sume RMBG 1.0 per output (cutout PNG only; bills image + remove-background).\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeImageGenerationRequest"},"examples":{"text_to_image":{"summary":"Text to image","value":{"prompt":"A clean product hero image for a new AI video ad platform, studio lighting, premium SaaS visual style","aspect_ratio":"1:1","quality":"high","num_images":1,"output_format":"png","mode":"async"}},"image_reference_edit":{"summary":"Image reference/edit","value":{"prompt":"Create a polished product ad image using the reference UI and premium studio lighting.","image_urls":["https://example.com/inputs/product-reference.png"],"image_size":"landscape_16_9","quality":"high","num_images":1,"output_format":"png"}},"webhook_usage":{"summary":"Webhook callback","value":{"prompt":"A vertical launch image for a creator analytics dashboard.","aspect_ratio":"9:16","num_images":1,"mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"deprecated":true,"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Image generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Image generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"image_generation","status":"queued","model":"sume/image-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/image-1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"prompt\": \"A clean product hero image for a new AI video ad platform, studio lighting, premium SaaS visual style\",\n  \"aspect_ratio\": \"1:1\",\n  \"quality\": \"high\",\n  \"num_images\": 1,\n  \"output_format\": \"png\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/video-1.0/runs":{"post":{"operationId":"runSumeVideoV1Model","summary":"Run Sume Video 1.0 (retiring soon)","tags":["Models"],"description":"Retiring soon. Compatibility alias for Video Router Auto (POST /v1/videos with sume/auto). Legacy routing_preset is ignored.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoGenerationRequest"},"examples":{"text_to_video":{"summary":"Text to video","value":{"prompt":"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.","resolution":"720p","duration":8,"aspect_ratio":"9:16","generate_audio":false,"routing_preset":"cost","mode":"async"}},"image_to_video":{"summary":"Image to video with first/end frames","value":{"prompt":"Animate the subject with subtle camera movement and realistic hand motion. Keep the face stable.","image_url":"https://example.com/inputs/first-frame.png","end_image_url":"https://example.com/inputs/end-frame.png","resolution":"720p","duration":8,"aspect_ratio":"9:16","generate_audio":false}},"reference_to_video":{"summary":"Reference to video","value":{"prompt":"Create a realistic vertical UGC ad using @Image1 and @Video1 as references. Keep the camera handheld and natural.","reference_image_urls":["https://example.com/inputs/avatar-reference.png","https://example.com/inputs/product-ui.png"],"reference_video_urls":["https://example.com/inputs/style-reference.mp4"],"resolution":"720p","duration":8,"aspect_ratio":"9:16","generate_audio":true}},"webhook_usage":{"summary":"Webhook callback","value":{"prompt":"A cinematic product reveal for a new dashboard.","duration":6,"aspect_ratio":"16:9","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"deprecated":true,"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Video generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Video generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/video-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/video-1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"prompt\": \"A vertical UGC-style ad clip showing a founder opening an AI video dashboard on a laptop, natural office lighting.\",\n  \"resolution\": \"720p\",\n  \"duration\": 8,\n  \"aspect_ratio\": \"9:16\",\n  \"generate_audio\": false,\n  \"routing_preset\": \"cost\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/music-1.0/runs":{"post":{"operationId":"runSumeMusicV1Model","summary":"Run Sume Music 1.0","tags":["Models"],"description":"Canonical Sume Music 1.0 model-run endpoint. Accepts provider-hidden public music generation inputs without a `model` field and submits a Sume-owned music generation job.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeMusicGenerationRequest"},"examples":{"text_to_music":{"summary":"Text to music","value":{"prompt":"An upbeat indie-pop instrumental with bright acoustic guitar and a catchy chorus energy about starting something new. No vocals, no spoken word.","mode":"async"}},"image_conditioned_music":{"summary":"Image-conditioned music","value":{"prompt":"Cinematic ambient score that matches the mood of the attached still.","image_url":"https://example.com/inputs/moodboard.png","mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"prompt":"A short lo-fi beat for a product demo montage.","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Music generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"Music generation queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"music_generation","status":"queued","model":"sume/music-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/music-1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"prompt\": \"An upbeat indie-pop instrumental with bright acoustic guitar and a catchy chorus energy about starting something new. No vocals, no spoken word.\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/stt-1.0/runs":{"post":{"operationId":"runSumeSttV1Model","summary":"Run Sume STT 1.0","tags":["Models"],"description":"Canonical Sume STT 1.0 model-run endpoint. Accepts provider-hidden public speech-to-text inputs without a `model` field and submits a Sume-owned STT job. Completed results carry `text`, language fields when available, and `words[]` word-level timings.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeSttTranscribeRequest"},"examples":{"transcribe_audio":{"summary":"Transcribe audio","value":{"audio_url":"https://media.sume.com/artifacts/example/clip.m4a","language_code":"ko","duration_seconds":20,"mode":"async"}},"auto_detect_language":{"summary":"Auto-detect language","value":{"audio_url":"https://media.sume.com/artifacts/example/clip.wav","mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"audio_url":"https://media.sume.com/artifacts/example/clip.m4a","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"STT job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"STT job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"speech_to_text","status":"queued","model":"sume/stt-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/stt-1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"audio_url\": \"https://media.sume.com/artifacts/example/clip.m4a\",\n  \"language_code\": \"ko\",\n  \"duration_seconds\": 20,\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/tts-1.0/runs":{"post":{"operationId":"runSumeTtsV1Model","summary":"Run Sume TTS 1.0","tags":["Models"],"description":"Canonical Sume TTS 1.0 model-run endpoint. Accepts public text-to-speech inputs without a top-level Sume `model` field and submits a Sume-owned text_to_speech job.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTtsGenerateRequest"},"examples":{"generate_speech":{"summary":"Generate speech","value":{"transcript":"Hello from Sume TTS.","voice":{"mode":"id","id":"9f3e2b1c-6a4d-4c8e-9f1a-2b3c4d5e6f70"},"output_format":{"container":"mp3","sample_rate":44100,"bit_rate":128000},"mode":"async"}},"generate_speech_from_avatar":{"summary":"Generate speech using an avatar voice","value":{"transcript":"Hello from this avatar.","avatar_id":"avtr_example","output_format":{"container":"wav","encoding":"pcm_s16le","sample_rate":44100},"mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"transcript":"Hello from Sume TTS.","voice":{"id":"9f3e2b1c-6a4d-4c8e-9f1a-2b3c4d5e6f70"},"mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"TTS job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"TTS job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"text_to_speech","status":"queued","model":"sume/tts-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/tts-1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"transcript\": \"Hello from Sume TTS.\",\n  \"voice\": {\n    \"mode\": \"id\",\n    \"id\": \"9f3e2b1c-6a4d-4c8e-9f1a-2b3c4d5e6f70\"\n  },\n  \"output_format\": {\n    \"container\": \"mp3\",\n    \"sample_rate\": 44100,\n    \"bit_rate\": 128000\n  },\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/rmbg-1.0/runs":{"post":{"operationId":"runSumeRmbgV1Model","summary":"Run Sume RMBG 1.0","tags":["Models"],"description":"Canonical Sume RMBG 1.0 model-run endpoint. Accepts provider-hidden public background-removal inputs without a `model` field and submits a Sume-owned RMBG job.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeRmbgRemoveRequest"},"examples":{"remove_background":{"summary":"Remove background","value":{"image_url":"https://example.com/inputs/portrait.png","mode":"async"}},"webhook_usage":{"summary":"Webhook callback","value":{"image_url":"https://media.sume.com/artifacts/example/input.png","mode":"webhook","webhook_url":"https://example.com/webhooks/sume"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"RMBG job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"},"examples":{"async_queued":{"summary":"RMBG job queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"background_removal","status":"queued","model":"sume/rmbg-1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/rmbg-1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"image_url\": \"https://example.com/inputs/portrait.png\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/video-upscale-1.0/runs":{"post":{"operationId":"runSumeVideoUpscaleV1Model","summary":"Run Sume Video Upscale 1.0","tags":["Models"],"description":"Canonical Sume Video Upscale 1.0 model-run endpoint. Accepts provider-hidden public upscale inputs without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeVideoUpscaleRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/models/veed/fabric-1.0/runs":{"post":{"operationId":"runVeedFabric10Model","summary":"Run VEED Fabric 1.0","tags":["Models"],"description":"Canonical VEED Fabric 1.0 model-run endpoint. Accepts provider-hidden public image-to-video inputs without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAvatarImageToVideoRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/models/sume/avatar-1.0/image-to-video/runs":{"post":{"operationId":"runSumeAvatarImageToVideoModel","summary":"Run VEED Fabric 1.0 (deprecated model-run alias)","tags":["Models"],"description":"Deprecated / retiring. Compatibility alias; still supported for existing integrations. Use `POST /v1/veed/fabric-1.0` or its canonical model-run twin `POST /v1/models/veed/fabric-1.0/runs` (public model id `veed/fabric-1.0`) with the same request body: `audio_url`, `duration_seconds`, and exactly one visual source. Prefer `image_url` of the generated, inspected posed still; use `avatar_handle` instead only if the user named that avatar (XOR, never both).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAvatarImageToVideoRequest"}}}},"deprecated":true,"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/models/sume/avatar-1.0/fabric/runs":{"post":{"operationId":"runSumeAvatarFabricModel","summary":"Run Sume Avatar 1.0 Fabric (experimental)","tags":["Models"],"description":"EXPERIMENTAL model-run twin of `POST /v1/avatar-1.0/fabric`. Accepts provider-hidden public inputs without a `model` field. Test-only surface: the model id will change before general availability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeAvatarFabricRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/kling/3.0/motion-control/runs":{"post":{"operationId":"runKlingMotionControlModel","summary":"Run Kling 3.0 Motion Control","tags":["Models"],"description":"Canonical Kling 3.0 Motion Control model-run endpoint. Accepts provider-hidden public motion-control inputs without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeKlingMotionControlRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/models/sume/avatar-1.0/motion-control/runs":{"post":{"operationId":"runSumeAvatarMotionControlModel","summary":"Run Kling 3.0 Motion Control (face-control model id)","tags":["Models"],"description":"Face-control model-run alias of `POST /v1/models/kling/3.0/motion-control/runs`. Same body; created jobs store the public model id `kling/3.0/motion-control`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeKlingMotionControlRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}]}},"/v1/models/sume/timeline-1.0/runs":{"post":{"operationId":"runSumeTimelineV1Model","summary":"Run Sume Timeline 1.0","tags":["Models"],"description":"Canonical Sume Timeline 1.0 model-run endpoint. Accepts the same declarative timeline body as POST /v1/timeline-1.0/render without a `model` field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SumeTimelineRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"202":{"description":"Job submission envelope. Placeholder runtimes return 202 while the queued job is not terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitJobResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/avatar/v1.0/runs":{"post":{"operationId":"runSumeAvatarV1Model","summary":"Run Sume Avatar 1.0","tags":["Models"],"description":"Canonical high-level Sume Avatar 1.0 workflow endpoint. New avatars complete only after Sume has produced the base avatar, idle still, idle video, processed preview video, and loop artifact. Provider implementation ids stay internal; responses return Sume-owned run, resource, step, polling, result, event, and cancel URLs.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarModelRunRequest"},"examples":{"prompt_avatar":{"summary":"Create an avatar from a prompt","value":{"avatar_handle":"mina","input":{"type":"prompt","prompt":"A friendly Korean presenter"},"mode":"async"}},"photo_avatar":{"summary":"Create an avatar from a photo URL","value":{"avatar_handle":"uploaded_presenter","input":{"type":"photo","image_url":"https://example.com/inputs/presenter.png"},"mode":"sync","wait_timeout_seconds":20}},"props_avatar":{"summary":"Create an avatar from public props","value":{"avatar_handle":"yuna_creator","input":{"type":"props","ethnicity":"Asian","sex":"female","age":25},"mode":"async"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume-owned model-run submission envelope. Use the returned Sume job URLs for lifecycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRunResponse"},"examples":{"async_queued":{"summary":"Avatar workflow accepted","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"sync","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Sume-owned model-run submission envelope. Use the returned Sume job URLs for lifecycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRunResponse"},"examples":{"async_queued":{"summary":"Avatar workflow accepted","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"sync","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar model-run submit conflicts. Possible stable `error.code` values: `avatar_handle_taken`, `avatar_handle_reserved`, `idempotency_conflict`, or `avatar_not_ready` when creating a video from an existing avatar that is not ready.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_handle_taken":{"summary":"Handle already exists","value":{"error":{"code":"avatar_handle_taken","message":"Avatar handle @studio_presenter is already in use.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_handle_taken","next_action":"fix_input","details":{"handle":"studio_presenter","avatar_id":"avtr_0123456789abcdef"}}}},"avatar_handle_reserved":{"summary":"Handle prefix is reserved","value":{"error":{"code":"avatar_handle_reserved","message":"@sume_presenter uses the reserved sume_ avatar handle prefix. Choose a non-reserved handle for user-created avatars.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_handle_reserved","next_action":"fix_input","details":{"handle":"sume_presenter","reserved_prefix":"sume_","reserved_for":"system_avatars"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/avatar/v1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"mina\",\n  \"input\": {\n    \"type\": \"prompt\",\n    \"prompt\": \"A friendly Korean presenter\"\n  },\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/avatar-video/v1.0/runs":{"post":{"operationId":"runSumeAvatarVideoV1Model","summary":"Run Sume Avatar Video 1.0","tags":["Models"],"description":"Canonical Sume Avatar Video 1.0 model endpoint. Creates a durable avatar-video resource and queued Sume job from a ready avatar, with provider implementation ids kept internal. This concrete model URL returns the same resource submit envelope as `/v1/avatar-videos` for backward compatibility.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoCreateRequest"},"examples":{"avatar_video_model_run":{"summary":"Run Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","script":"Share a quick product benefit in one concise sentence.","product_image":"https://example.com/inputs/product.png","scene":{"type":"prompt","prompt":"Bright product demo set"},"quality":"max","aspect_ratio":"9:16","mode":"async"}},"productless_avatar_video_model_run":{"summary":"Run productless Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","script":"Share a quick update in one concise sentence.","quality":"plus","mode":"sync","wait_timeout_seconds":20}},"multi_scene_avatar_video_model_run":{"summary":"Run multi-scene Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","aspect_ratio":"9:16","quality":"plus","mode":"async","video_inputs":[{"id":"hook","voice":{"type":"text","script":"Wait, this turned one selfie into a whole video?","duration":3},"background":{"type":"prompt","prompt":"Casual bedroom or couch background, selfie-camera framing, native UGC lighting."}},{"id":"demo","voice":{"type":"text","input_text":"You pick a template, drop in your photo, and it builds the clip around you.","duration":5},"background":{"type":"prompt","prompt":"Casual bedroom or couch background, selfie-camera framing, native UGC lighting."}}]}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"202":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar-video submit conflicts. Possible stable `error.code` values: `avatar_not_ready` when the referenced avatar is not ready, or `idempotency_conflict` when the Idempotency-Key was reused for a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_not_ready":{"summary":"Referenced avatar is not video-ready","value":{"error":{"code":"avatar_not_ready","message":"Avatar is not ready for video generation.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_not_ready","next_action":"inspect_events","details":{"avatar_id":"avtr_0123456789abcdef","status":"processing"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/avatar-video/v1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"sume_clawra\",\n  \"script\": \"Share a quick product benefit in one concise sentence.\",\n  \"product_image\": \"https://example.com/inputs/product.png\",\n  \"scene\": {\n    \"type\": \"prompt\",\n    \"prompt\": \"Bright product demo set\"\n  },\n  \"quality\": \"max\",\n  \"aspect_ratio\": \"9:16\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/avatar-face-swap/v1.0/runs":{"post":{"operationId":"runSumeAvatarFaceSwapV1Model","summary":"Run Sume Avatar Face Swap 1.0 Beta","tags":["Models"],"description":"Beta Sume Avatar Face Swap 1.0 endpoint. Creates a queued avatar face-swap resource from a ready avatar handle and public HTTPS source video. Provider implementation details are kept internal.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarFaceSwapCreateRequest"},"examples":{"avatar_face_swap_beta_model_run":{"summary":"Run Avatar Face Swap 1.0 Beta","value":{"avatar_handle":"sume_clawra","video_url":"https://example.com/inputs/source-video.mp4","quality":"standard","mode":"async"}},"avatar_face_swap_beta_sync":{"summary":"Run beta face swap and wait briefly","value":{"avatar_handle":"sume_david","video_url":"https://example.com/inputs/talking-clip.mp4","quality":"plus","mode":"sync","wait_timeout_seconds":20}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued beta avatar face-swap resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarFaceSwapSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar face-swap resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_face_swap","status":"queued","model":"sume/avatar-face-swap/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_face_swap_id":"avfs_0123456789abcdef","avatar_face_swap":{"id":"avfs_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"artifacts":[],"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_face_swap","status":"queued","model":"sume/avatar-face-swap/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_face_swap_id":"avfs_0123456789abcdef","avatar_face_swap":{"id":"avfs_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"artifacts":[],"result":null,"error":null}}}}}}}},"202":{"description":"Queued beta avatar face-swap resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarFaceSwapSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar face-swap resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_face_swap","status":"queued","model":"sume/avatar-face-swap/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_face_swap_id":"avfs_0123456789abcdef","avatar_face_swap":{"id":"avfs_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"artifacts":[],"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_face_swap","status":"queued","model":"sume/avatar-face-swap/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_face_swap_id":"avfs_0123456789abcdef","avatar_face_swap":{"id":"avfs_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"artifacts":[],"result":null,"error":null}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_not_ready":{"summary":"Referenced avatar is not ready","value":{"error":{"code":"avatar_not_ready","message":"Avatar is not ready for video generation.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_not_ready","next_action":"inspect_events","details":{"avatar_id":"avtr_0123456789abcdef","status":"processing"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/avatar-face-swap/v1.0/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"sume_clawra\",\n  \"video_url\": \"https://example.com/inputs/source-video.mp4\",\n  \"quality\": \"standard\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/video-captions":{"post":{"operationId":"submitVideoCaptionJob","summary":"Submit video caption job","tags":["Video Captions"],"description":"Creates a queued video caption resource using a public caption style. Speech-to-captions: optional script_text locks burned-in wording to a predetermined script while speech-to-text timings remain the timing source of truth. If alignment cannot map script_text onto speech timings, the job fails with typed public reasons `script_alignment_mismatch` or `script_alignment_failed` (next_action `simplify_script_text_or_omit`); omit script_text to use STT wording. Overlay / silent clips: pass `cues` or `segments` (text+start+end) to skip speech-to-text — a no-speech STT result is `caption_no_speech` (next_action `use_overlay_captions`), not a generic policy reject. Each accepted job reserves and captures 13 credits for videos up to 60 seconds under the current fixed estimate. Renderer, speech-to-text provider, browser/runtime, temporary path, and provider task details stay internal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoCaptionCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued video caption resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoCaptionSubmitResponse"}}}},"202":{"description":"Queued video caption resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoCaptionSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-captions/{id}":{"get":{"operationId":"getVideoCaption","summary":"Get video caption resource","tags":["Video Captions"],"description":"Returns public-safe video caption status and output metadata. Provider, renderer, raw transcript, temporary path, and signed source URL internals are omitted.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video caption resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoCaptionResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/media-imports":{"post":{"operationId":"submitMediaImportJob","summary":"Submit media import job","tags":["Media Imports"],"description":"Imports a public TikTok or Instagram video URL into Sume-owned storage. Creates a queued media_import job and mimp_ resource, fetches the media, mirrors bytes to media.sume.com, and records a workspace asset with status mirrored. Fixed estimate 10 credits per accepted import. YouTube and other hosts are rejected with unsupported_platform. Practical size cap ~2GB. Returned URLs are URL-first inputs for generators — no media_id gate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaImportCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued media import resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaImportSubmitResponse"}}}},"202":{"description":"Queued media import resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaImportSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/media-imports/{id}":{"get":{"operationId":"getMediaImport","summary":"Get media import resource","tags":["Media Imports"],"description":"Returns public-safe media import status, durable media.sume.com URL, asset id, and source metadata. Provider download URLs and internals are omitted.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Media import resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaImportResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-frames":{"post":{"operationId":"submitVideoFramesJob","summary":"Extract frames from a Sume-hosted video","tags":["Video Frames"],"description":"Extracts stills from a media.sume.com video at times the caller names (`at[]`) or at a rate (`fps`), and returns them as durable media.sume.com image artifacts. Sume compiles the ffmpeg: there is no filtergraph, codec, or ffmpeg field on this route, and any of vf/filter/filter_complex/select/ffmpeg/cmd/codec/crf/preset is rejected with ffmpeg_fields_rejected. Runs on the media ffmpeg runtime. Reserved at the job's compute ceiling and captured at its own compute, never above the reservation. Source duration cap 300s, 24 frames per call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoFramesCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"202":{"description":"Queued video frames job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoFramesSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-frames/{id}":{"get":{"operationId":"getVideoFrames","summary":"Get extracted frames","tags":["Video Frames"],"description":"Returns the extract's status and, once ready, frames[{t,url,width,height}] as durable media.sume.com image artifacts. The id is the request_id from submit — there is no separate resource id.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video frames resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoFramesResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-inspect":{"post":{"operationId":"submitVideoInspectJob","summary":"Probe, sample stills from, and optionally transcribe a hosted video","tags":["Video Inspect 1.0"],"description":"Probes one media.sume.com video (duration, size, rotation, fps, codecs, audio, HDR), samples up to 24 stills as durable media.sume.com image artifacts, and with transcribe true extracts speech with word timings through Sume STT 1.0. Read-only: never re-encodes the source, never produces an MP4. Reserved at the job's compute ceiling and captured at its own compute, never above the reservation; transcribe adds the STT 1.0 per-minute rate to the reservation and the capture. Default mode sync waits up to 30 seconds and answers 200 with the finished inspect, or 202 with the queued job to poll. Sume compiles the ffmpeg: vf / filter / ffmpeg / cmd / codec / crf and friends are rejected with ffmpeg_fields_rejected. Source cap 1800 seconds; 24 stills per call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoInspectCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video inspect job envelope: finished (200) when the sync wait caught it, queued (202) otherwise.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoInspectSubmitResponse"}}}},"202":{"description":"Video inspect job envelope: finished (200) when the sync wait caught it, queued (202) otherwise.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoInspectSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-inspect/{id}":{"get":{"operationId":"getVideoInspect","summary":"Get a video inspect","tags":["Video Inspect 1.0"],"description":"Returns the inspect's status and, once ready, probe facts, frames[{t,url,width,height}] as durable media.sume.com image artifacts, and the transcript when one was requested. The id is the request_id from submit — there is no separate resource id.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video inspect resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoInspectResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/reference-ingest":{"post":{"operationId":"submitReferenceIngestJob","summary":"Run the deterministic reference preflight on a hosted video and return its manifest","tags":["Reference Ingest 1.0"],"description":"Reads ONE media.sume.com reference clip (≤300 s) into a ReferenceVideoManifest: probe facts, shots[] with frame-exact cuts and one source-resolution keyframe each, text_tracks[] from source-resolution OCR (text, box, span, confidence), audio{silent, speech, music} facts, one labeled overview strip and native crops for low-confidence text. Read-only: never re-encodes the source, never produces an MP4. A reference_remix read transcribes its speech by default (speech.allow_billed_stt omitted counts as true for that purpose; false opts out), which adds the STT 1.0 per-minute rate to the reservation and settles that part to zero when the track is silent or carries no speech; other purposes transcribe only when allow_billed_stt is true. Every ingest is reserved at its compute ceiling and captured at its own compute, never above the reservation. Default mode sync waits up to 30 seconds and answers 200 with the finished manifest, or 202 with the queued job to poll. Sume compiles every pass: vf / filter / ffmpeg / cmd / codec / crf and friends are rejected with ffmpeg_fields_rejected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceIngestCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Reference ingest job envelope: finished (200) when the sync wait caught it, queued (202) otherwise.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceIngestSubmitResponse"}}}},"202":{"description":"Reference ingest job envelope: finished (200) when the sync wait caught it, queued (202) otherwise.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceIngestSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/reference-ingest/{id}":{"get":{"operationId":"getReferenceIngest","summary":"Get a reference ingest","tags":["Reference Ingest 1.0"],"description":"Returns the ingest's status and, once ready, the ReferenceVideoManifest (shots, text tracks, audio facts, overview strip, uncertain[] and provenance) with every image as a durable media.sume.com artifact. The id is the request_id from submit — there is no separate resource id.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Reference ingest resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceIngestResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/probe":{"post":{"operationId":"submitRemixMedia_probe","summary":"Remix media: probe","tags":["Remix media 1.0"],"description":"Fetch ONE media.sume.com reference clip (≤300 s) into the remix-media Volume, probe it and cut its 16 kHz wav. The response's request_id is the understanding_id every later verb binds to. Reserved at the call's compute ceiling and captured at its own compute, never above the reservation. Default mode sync waits up to 30 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/transcribe":{"post":{"operationId":"submitRemixMedia_transcribe","summary":"Remix media: transcribe","tags":["Remix media 1.0"],"description":"Transcribe the understanding's audio into remix.transcript/1 (passages → words with a 0–1 score). Default engine whisperx (WhisperX on the media box, per-word alignment scores), reserved at its compute ceiling and captured at its own compute, never above the reservation — no STT line; engine scribe_v2 = Sume STT 1.0, which bills the per-minute rate on the probe's duration; settled to zero when the probe said the track is silent. allow_billed_stt must be true.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/boundaries":{"post":{"operationId":"submitRemixMedia_boundaries","summary":"Remix media: boundaries","tags":["Remix media 1.0"],"description":"Mechanical adjacent-frame change candidates (12 fps, 32×32 mean absolute difference, threshold 0.1) as remix.boundaries/1. Never editorial shot labels. Captured at its own compute, never above the reservation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/tile":{"post":{"operationId":"submitRemixMedia_tile","summary":"Remix media: tile","tags":["Remix media 1.0"],"description":"Exact frames at the requested instants — at[], around a spoken phrase, ranges[], or start/end with every|frames — or every frame of a short interval, each labeled with its timecode and the words spoken at that instant, composed into grid pages (layout grid) or single native-size pictures (layout frames). Pages are sized so every cell survives the agent host's 1080 px inline downscale. Captured at its own compute, never above the reservation; every page is a durable image artifact.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/cut":{"post":{"operationId":"submitRemixMedia_cut","summary":"Remix media: cut","tags":["Remix media 1.0"],"description":"A [start, end) excerpt of the reference, or ordered kept spans joined on a fresh clock, with the source time burned on every frame when label_time is true. Captured at its own compute, never above the reservation; the excerpt is a durable video artifact with a source ↔ output mapping.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/notes":{"post":{"operationId":"submitRemixMedia_notes","summary":"Remix media: notes","tags":["Remix media 1.0"],"description":"Store ANALYSIS.md, TIMELINE.md or PROGRESS.md (the reference reading) or FORMAT.md / TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment) for this understanding as a text artifact. Rewritten when the reading changes: the newest note of each name is the one the bundle returns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/align":{"post":{"operationId":"submitRemixMedia_align","summary":"Remix media: align","tags":["Remix media 1.0"],"description":"Align one script.svml segment to a generated take's transcript (the take's own sume_probe + sume_transcribe): every script token gets the measured start / end / score of the transcript words it paired with, cue breaks, selections and moments resolve to word boundaries, and an unmatched word stays untimed. Stored as remix.take/1 (take.json + script.svml artifacts); the composition step binds only these times. Unbilled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected).","properties":{"video_url":{"type":"string","format":"uri"},"understanding_id":{"type":"string"},"language":{"type":"string","minLength":2,"maxLength":16},"engine":{"type":"string","enum":["whisperx","scribe_v2"]},"checkpoint":{"type":"string","enum":["small","medium","large-v3-turbo","large-v3"]},"allow_billed_stt":{"type":"boolean"},"rate":{"type":"number","minimum":1,"maximum":60},"threshold":{"type":"number","minimum":0,"maximum":1},"layout":{"type":"string","enum":["grid","frames"]},"name":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96},"at":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":96},"around":{"type":"object","additionalProperties":false,"required":["phrase"],"properties":{"phrase":{"type":"string","minLength":1,"maxLength":200},"occurrence":{"type":"integer","minimum":1,"maximum":50},"padding":{"type":"number","minimum":0,"maximum":10}}},"ranges":{"type":"array","minItems":1,"maxItems":24,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"id":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"every":{"type":"number","minimum":0.04},"frames":{"type":"integer","minimum":2,"maximum":96}}}},"every_frame":{"type":"boolean"},"cell":{"type":"integer","minimum":80,"maximum":1080},"columns":{"type":"integer","minimum":1,"maximum":6},"rows":{"type":"integer","minimum":1,"maximum":6},"fit_inline":{"type":"boolean"},"label_time":{"type":"boolean"},"transcript":{"type":"boolean"},"transcript_job_id":{"type":"string"},"keep":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}}}},"markdown":{"type":"string","minLength":1},"take_understanding_id":{"type":"string"},"script":{"type":"string","minLength":1},"segment":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["sync","async","webhook"]},"webhook_url":{"type":"string","format":"uri"},"wait_timeout_seconds":{"type":"integer","minimum":0,"maximum":30}}}}},"description":"Remix media 1.0 request, one body per verb. probe: video_url (media.sume.com, workspace-owned, ≤300 s; audio only for a generated voice take) — the response's request_id is the understanding_id. transcribe: understanding_id, language (e.g. ko; omitted = WhisperX detects it), engine whisperx (default: the remix procedure's engine upstream on the media box, a score on every aligned word, charged at its own compute, never above the reservation) or scribe_v2 (Sume STT 1.0: allow_billed_stt true, bills the per-minute rate on the probe's duration, settles to zero when the track is silent, no per-word score), checkpoint (whisperx checkpoint: small default, on CPU; medium, large-v3-turbo, large-v3 opt-in on the GPU). boundaries: understanding_id, rate (1–60, default 12), threshold (0–1, default 0.1). tile: understanding_id, layout grid|frames, one of at[] | around {phrase, occurrence, padding} | ranges[] | start/end with every|frames, every_frame, cell (80–1080, default 480), columns, rows, fit_inline, label_time, transcript, transcript_job_id, name. cut: understanding_id, start/end or keep[] (≤120 s total), label_time, name. notes: understanding_id, name ANALYSIS.md|TIMELINE.md|PROGRESS.md (the reference reading) or FORMAT.md|TREATMENT.md (the project: why the format works and which spoken words its captions stick to; the target treatment), markdown. align: understanding_id (the project), take_understanding_id (the probe of the generated take), transcript_job_id (that take's transcribe), script (script.svml), segment — the segment's words aligned to the take's measured words as remix.take/1 (no time is invented; an unmatched word stays untimed). Default mode is sync with a 30-second wait. No ffmpeg, filtergraph or codec field on any verb (ffmpeg_fields_rejected)."},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["request_id","understanding_id","idempotency_hit","job","remix_media"],"properties":{"request_id":{"type":"string"},"understanding_id":{"type":"string"},"status_url":{"type":"string"},"result_url":{"type":"string"},"idempotency_hit":{"type":"boolean"},"job":{"type":"object","additionalProperties":true},"remix_media":{"type":"object","additionalProperties":true},"usage":{"type":"object","nullable":true,"additionalProperties":true},"sync":{"type":"object","nullable":true,"additionalProperties":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/remix-media/{id}":{"get":{"operationId":"getRemixMedia","summary":"Get a Remix media job, or the whole understanding bundle for a probe id","tags":["Remix media 1.0"],"description":"For any remix_media job id: its status and result. For a probe's id (the understanding_id) the data also carries bundle: remix.understanding/1 — probe and audio facts, the transcript and boundaries refs, every evidence artifact (tile pages, labeled frames, cut excerpts) the newest note of each name (ANALYSIS.md / TIMELINE.md / PROGRESS.md / FORMAT.md / TREATMENT.md) and every aligned take (takes[]), each with a durable artifact id.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_profile":{"post":{"operationId":"scrapecreators_instagram_profile","summary":"Public social instagram_profile","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":31,"pattern":"^@?[A-Za-z0-9._]{1,30}$"}},"required":["handle"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_reels":{"post":{"operationId":"scrapecreators_instagram_reels","summary":"Public social instagram_reels","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","minLength":1,"maxLength":30,"pattern":"^[0-9]{1,30}$"},"handle":{"type":"string","minLength":1,"maxLength":31,"pattern":"^@?[A-Za-z0-9._]{1,30}$"},"max_id":{"type":"string","minLength":1,"maxLength":2048},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":[],"additionalProperties":false,"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_posts":{"post":{"operationId":"scrapecreators_instagram_posts","summary":"Public social instagram_posts","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":31,"pattern":"^@?[A-Za-z0-9._]{1,30}$"},"next_max_id":{"type":"string","minLength":1,"maxLength":2048},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["handle"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_media":{"post":{"operationId":"scrapecreators_instagram_media","summary":"Public social instagram_media","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"region":{"type":"string","minLength":1,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","minLength":1,"maxLength":64}},"required":[],"additionalProperties":false,"anyOf":[{"required":["url"]},{"required":["shortcode"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_profile":{"post":{"operationId":"scrapecreators_tiktok_profile","summary":"Public social tiktok_profile","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":31,"pattern":"^@?[A-Za-z0-9._]{1,30}$"},"user_id":{"type":"string","minLength":1,"maxLength":30,"pattern":"^[0-9]{1,30}$"}},"required":[],"additionalProperties":false,"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_videos":{"post":{"operationId":"scrapecreators_tiktok_videos","summary":"Public social tiktok_videos","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":31,"pattern":"^@?[A-Za-z0-9._]{1,30}$"},"user_id":{"type":"string","minLength":1,"maxLength":30,"pattern":"^[0-9]{1,30}$"},"max_cursor":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","minLength":1,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["handle"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_media":{"post":{"operationId":"scrapecreators_tiktok_media","summary":"Public social tiktok_media","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"region":{"type":"string","minLength":1,"maxLength":2,"pattern":"^[A-Za-z]{2}$"}},"required":["url"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_search":{"post":{"operationId":"scrapecreators_instagram_search","summary":"Public social instagram_search","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_search_profiles":{"post":{"operationId":"scrapecreators_instagram_search_profiles","summary":"Public social instagram_search_profiles","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","pattern":"^(?:[1-9]|1[01])$","minLength":1,"maxLength":2},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_search_reels":{"post":{"operationId":"scrapecreators_instagram_search_reels","summary":"Public social instagram_search_reels","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"date_posted":{"type":"string","enum":["last-week","last-month","last-year"],"minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":11},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_search_hashtag":{"post":{"operationId":"scrapecreators_instagram_search_hashtag","summary":"Public social instagram_search_hashtag","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hashtag":{"type":"string","minLength":1,"maxLength":256},"date_posted":{"type":"string","enum":["last-hour","last-day","last-week","last-month","last-year"],"minLength":1,"maxLength":256},"media_type":{"type":"string","enum":["all","reels"],"minLength":1,"maxLength":256},"cursor":{"type":"string","pattern":"^(?:[1-9]|1[01])$","minLength":1,"maxLength":2},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["hashtag"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/instagram_search_popular":{"post":{"operationId":"scrapecreators_instagram_search_popular","summary":"Public social instagram_search_popular","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":2048},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_search_users":{"post":{"operationId":"scrapecreators_tiktok_search_users","summary":"Public social tiktok_search_users","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_search_keyword":{"post":{"operationId":"scrapecreators_tiktok_search_keyword","summary":"Public social tiktok_search_keyword","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"date_posted":{"type":"string","enum":["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"],"minLength":1,"maxLength":256},"sort_by":{"type":"string","enum":["relevance","most-liked","date-posted"],"minLength":1,"maxLength":256},"region":{"type":"string","minLength":1,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"cursor":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_search_hashtag":{"post":{"operationId":"scrapecreators_tiktok_search_hashtag","summary":"Public social tiktok_search_hashtag","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hashtag":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","minLength":1,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"cursor":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["hashtag"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/scrapecreators/tiktok_search_top":{"post":{"operationId":"scrapecreators_tiktok_search_top","summary":"Public social tiktok_search_top","tags":["Public social discovery"],"description":"Public social read. Returns media candidates, not Sume-hosted media. At most 24 returned items and 3 feed pages. No Sume credit charge in v1; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means continue with jobs_wait then jobs_result using request_id. No login, stories, DMs, private accounts, or automatic import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":256},"publish_time":{"type":"string","enum":["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"],"minLength":1,"maxLength":256},"sort_by":{"type":"string","enum":["relevance","most-liked","date-posted"],"minLength":1,"maxLength":256},"region":{"type":"string","minLength":1,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"cursor":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":3},"order":{"type":"string","enum":["recent","play_count"],"default":"recent","description":"Sort the bounded sample locally; play_count is not an all-time account ranking."}},"required":["query"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_channel":{"post":{"operationId":"social_youtube_youtube_channel","summary":"Public YouTube youtube_channel","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._-]{1,100}$","maxLength":101,"description":"Channel handle, with or without @."},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"Channel id (UC…)."},"url":{"type":"string","maxLength":2048,"description":"Channel URL on youtube.com."}},"required":[],"anyOf":[{"required":["handle"]},{"required":["channel_id"]},{"required":["url"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_channel_videos":{"post":{"operationId":"social_youtube_youtube_channel_videos","summary":"Public YouTube youtube_channel_videos","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._-]{1,100}$","maxLength":101,"description":"Channel handle, with or without @."},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"Channel id (UC…)."},"sort":{"type":"string","enum":["latest","popular"]},"continuation_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":1}},"required":[],"anyOf":[{"required":["handle"]},{"required":["channel_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_channel_shorts":{"post":{"operationId":"social_youtube_youtube_channel_shorts","summary":"Public YouTube youtube_channel_shorts","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._-]{1,100}$","maxLength":101,"description":"Channel handle, with or without @."},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"Channel id (UC…)."},"sort":{"type":"string","enum":["newest","popular"]},"continuation_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":1}},"required":[],"anyOf":[{"required":["handle"]},{"required":["channel_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_community_posts":{"post":{"operationId":"social_youtube_youtube_community_posts","summary":"Public YouTube youtube_community_posts","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._-]{1,100}$","maxLength":101,"description":"Channel handle, with or without @."},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"Channel id (UC…)."},"continuation_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":1}},"required":[],"anyOf":[{"required":["handle"]},{"required":["channel_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_video":{"post":{"operationId":"social_youtube_youtube_video","summary":"Public YouTube youtube_video","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public YouTube video or Short URL (watch, shorts, youtu.be)."},"language":{"type":"string","pattern":"^[A-Za-z-]{2,10}$","maxLength":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_community_post":{"post":{"operationId":"social_youtube_youtube_community_post","summary":"Public YouTube youtube_community_post","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public YouTube community post URL (youtube.com/post/…)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_search":{"post":{"operationId":"social_youtube_youtube_search","summary":"Public YouTube youtube_search","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"type":{"type":"string","enum":["videos","shorts","channels"]},"upload_date":{"type":"string","enum":["today","this_week","this_month","this_year"]},"sort_by":{"type":"string","enum":["relevance","popular"]},"duration":{"type":"string","enum":["under_3_min","between_3_and_20_min","over_20_min"]},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2},"continuation_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10},"max_pages":{"type":"integer","minimum":1,"maximum":3,"default":1}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_search_suggestions":{"post":{"operationId":"social_youtube_youtube_search_suggestions","summary":"Public YouTube youtube_search_suggestions","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_comments":{"post":{"operationId":"social_youtube_youtube_comments","summary":"Public YouTube youtube_comments","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public YouTube video or Short URL (watch, shorts, youtu.be)."},"order":{"type":"string","enum":["top","newest"]},"continuation_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_comment_replies":{"post":{"operationId":"social_youtube_youtube_comment_replies","summary":"Public YouTube youtube_comment_replies","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"replies_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["replies_token"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_transcript":{"post":{"operationId":"social_youtube_youtube_transcript","summary":"Public YouTube youtube_transcript","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public YouTube video or Short URL (watch, shorts, youtu.be)."},"language":{"type":"string","pattern":"^[A-Za-z-]{2,10}$","maxLength":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_post_comments":{"post":{"operationId":"social_youtube_youtube_post_comments","summary":"Public YouTube youtube_post_comments","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public YouTube community post URL (youtube.com/post/…)."},"continuation_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube/youtube_post_comment_replies":{"post":{"operationId":"social_youtube_youtube_post_comment_replies","summary":"Public YouTube youtube_post_comment_replies","tags":["Public social discovery"],"description":"Public YouTube read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. No login, private content, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"replies_token":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["replies_token"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_followers":{"post":{"operationId":"social_read_instagram_followers","summary":"Public social instagram_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_following":{"post":{"operationId":"social_read_instagram_following","summary":"Public social instagram_following","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_likers":{"post":{"operationId":"social_read_instagram_likers","summary":"Public social instagram_likers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Instagram post or reel URL."},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","maxLength":64,"description":"Instagram shortcode (the id in /p/<shortcode>/)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["shortcode"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_similar":{"post":{"operationId":"social_read_instagram_similar","summary":"Public social instagram_similar","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_about":{"post":{"operationId":"social_read_instagram_about","summary":"Public social instagram_about","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_stories":{"post":{"operationId":"social_read_instagram_stories","summary":"Public social instagram_stories","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_highlights":{"post":{"operationId":"social_read_instagram_highlights","summary":"Public social instagram_highlights","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_highlight":{"post":{"operationId":"social_read_instagram_highlight","summary":"Public social instagram_highlight","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"highlight_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Highlight id from the highlights read."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["highlight_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_tagged":{"post":{"operationId":"social_read_instagram_tagged","summary":"Public social instagram_tagged","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_reposts":{"post":{"operationId":"social_read_instagram_reposts","summary":"Public social instagram_reposts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_comments":{"post":{"operationId":"social_read_instagram_comments","summary":"Public social instagram_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Instagram post or reel URL."},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","maxLength":64,"description":"Instagram shortcode (the id in /p/<shortcode>/)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["shortcode"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_comment_replies":{"post":{"operationId":"social_read_instagram_comment_replies","summary":"Public social instagram_comment_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Instagram post or reel URL."},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","maxLength":64,"description":"Instagram shortcode (the id in /p/<shortcode>/)."},"comment_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"The comment whose replies to read."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["comment_id"],"anyOf":[{"required":["url"]},{"required":["shortcode"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_transcript":{"post":{"operationId":"social_read_instagram_transcript","summary":"Public social instagram_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Instagram post or reel URL."},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","maxLength":64,"description":"Instagram shortcode (the id in /p/<shortcode>/)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["shortcode"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_audio_posts":{"post":{"operationId":"social_read_instagram_audio_posts","summary":"Public social instagram_audio_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"audio_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Instagram audio id (instagram.com/reels/audio/<id>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["audio_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_trending_reels":{"post":{"operationId":"social_read_instagram_trending_reels","summary":"Public social instagram_trending_reels","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_explore":{"post":{"operationId":"social_read_instagram_explore","summary":"Public social instagram_explore","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_explore_section":{"post":{"operationId":"social_read_instagram_explore_section","summary":"Public social instagram_explore_section","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"section_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Section id from the explore read."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["section_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_location":{"post":{"operationId":"social_read_instagram_location","summary":"Public social instagram_location","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"location_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Instagram location id."}},"required":["location_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_location_posts":{"post":{"operationId":"social_read_instagram_location_posts","summary":"Public social instagram_location_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"location_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Instagram location id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["location_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_search_places":{"post":{"operationId":"social_read_instagram_search_places","summary":"Public social instagram_search_places","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_search_hashtags":{"post":{"operationId":"social_read_instagram_search_hashtags","summary":"Public social instagram_search_hashtags","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_search_music":{"post":{"operationId":"social_read_instagram_search_music","summary":"Public social instagram_search_music","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/instagram_hashtag":{"post":{"operationId":"social_read_instagram_hashtag","summary":"Public social instagram_hashtag","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hashtag":{"type":"string","minLength":1,"maxLength":100,"description":"Hashtag, with or without #."}},"required":["hashtag"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_followers":{"post":{"operationId":"social_read_tiktok_followers","summary":"Public social tiktok_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["user_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_following":{"post":{"operationId":"social_read_tiktok_following","summary":"Public social tiktok_following","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_audience":{"post":{"operationId":"social_read_tiktok_audience","summary":"Public social tiktok_audience","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_region":{"post":{"operationId":"social_read_tiktok_region","summary":"Public social tiktok_region","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_similar":{"post":{"operationId":"social_read_tiktok_similar","summary":"Public social tiktok_similar","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_liked":{"post":{"operationId":"social_read_tiktok_liked","summary":"Public social tiktok_liked","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_reposts":{"post":{"operationId":"social_read_tiktok_reposts","summary":"Public social tiktok_reposts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_playlists":{"post":{"operationId":"social_read_tiktok_playlists","summary":"Public social tiktok_playlists","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_playlist":{"post":{"operationId":"social_read_tiktok_playlist","summary":"Public social tiktok_playlist","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"playlist_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"TikTok playlist (mix) id from the playlists read."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["playlist_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_sounds":{"post":{"operationId":"social_read_tiktok_sounds","summary":"Public social tiktok_sounds","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_comments":{"post":{"operationId":"social_read_tiktok_comments","summary":"Public social tiktok_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public TikTok video or photo URL."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_comment_replies":{"post":{"operationId":"social_read_tiktok_comment_replies","summary":"Public social tiktok_comment_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public TikTok video or photo URL."},"comment_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"The comment whose replies to read."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url","comment_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_transcript":{"post":{"operationId":"social_read_tiktok_transcript","summary":"Public social tiktok_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public TikTok video or photo URL."},"language":{"type":"string","pattern":"^[A-Za-z-]{2,10}$","maxLength":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_sound":{"post":{"operationId":"social_read_tiktok_sound","summary":"Public social tiktok_sound","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sound_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"TikTok sound (music) id."}},"required":["sound_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_sound_videos":{"post":{"operationId":"social_read_tiktok_sound_videos","summary":"Public social tiktok_sound_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sound_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"TikTok sound (music) id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["sound_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_trending_feed":{"post":{"operationId":"social_read_tiktok_trending_feed","summary":"Public social tiktok_trending_feed","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …).","default":"US"},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_explore":{"post":{"operationId":"social_read_tiktok_explore","summary":"Public social tiktok_explore","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","pattern":"^[0-9]{1,6}$","maxLength":6,"default":"120","description":"TikTok explore category code (120 = all)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_trending_hashtags":{"post":{"operationId":"social_read_tiktok_trending_hashtags","summary":"Public social tiktok_trending_hashtags","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …).","default":"US"},"period":{"type":"integer","enum":[7,30,90],"default":7},"industry":{"type":"string","enum":["apparel_accessories","baby_kids_maternity","beauty_personal_care","education","food_beverage","games","health","home_improvement","household_products","news_entertainment","pets","sports_outdoor","tech_electronics","travel","vehicle_transportation"]},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_trending_searches":{"post":{"operationId":"social_read_tiktok_trending_searches","summary":"Public social tiktok_trending_searches","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_music_charts":{"post":{"operationId":"social_read_tiktok_music_charts","summary":"Public social tiktok_music_charts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_popular_creators":{"post":{"operationId":"social_read_tiktok_popular_creators","summary":"Public social tiktok_popular_creators","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"follower_count":{"type":"string","pattern":"^[0-9KMB+-]{2,16}$","maxLength":16,"description":"Follower range, e.g. 10K-100K."},"creator_country":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"audience_country":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"sort_by":{"type":"string","pattern":"^[a-z_]{1,32}$","maxLength":32,"description":"engagement, follower count or average views."},"page":{"type":"integer","minimum":1,"maximum":20},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_insights":{"post":{"operationId":"social_read_tiktok_search_insights","summary":"Public social tiktok_search_insights","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"tab":{"type":"string","enum":["all","content_gap","follower_searched","life_style","topics","challenges","sounds","hashtags"],"default":"all"},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_insight":{"post":{"operationId":"social_read_tiktok_search_insight","summary":"Public social tiktok_search_insight","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"query_id_str from the search insights read."},"time_range":{"type":"string","enum":["past_7_days","past_30_days","past_60_days","past_6_months"]}},"required":["query_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_insight_trend":{"post":{"operationId":"social_read_tiktok_search_insight_trend","summary":"Public social tiktok_search_insight_trend","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"query_id_str from the search insights read."}},"required":["query_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_insight_videos":{"post":{"operationId":"social_read_tiktok_search_insight_videos","summary":"Public social tiktok_search_insight_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_suggestions":{"post":{"operationId":"social_read_tiktok_search_suggestions","summary":"Public social tiktok_search_suggestions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_photos":{"post":{"operationId":"social_read_tiktok_search_photos","summary":"Public social tiktok_search_photos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_lives":{"post":{"operationId":"social_read_tiktok_search_lives","summary":"Public social tiktok_search_lives","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_music":{"post":{"operationId":"social_read_tiktok_search_music","summary":"Public social tiktok_search_music","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_places":{"post":{"operationId":"social_read_tiktok_search_places","summary":"Public social tiktok_search_places","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_search_hashtags":{"post":{"operationId":"social_read_tiktok_search_hashtags","summary":"Public social tiktok_search_hashtags","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_hashtag":{"post":{"operationId":"social_read_tiktok_hashtag","summary":"Public social tiktok_hashtag","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hashtag":{"type":"string","minLength":1,"maxLength":100,"description":"Hashtag, with or without #."}},"required":["hashtag"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_status":{"post":{"operationId":"social_read_tiktok_live_status","summary":"Public social tiktok_live_status","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_room":{"post":{"operationId":"social_read_tiktok_live_room","summary":"Public social tiktok_live_room","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"room_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Live room id (roomId from the live status read)."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."}},"required":["room_id","user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_gifts":{"post":{"operationId":"social_read_tiktok_live_gifts","summary":"Public social tiktok_live_gifts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"room_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Live room id."}},"required":["room_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_ranking":{"post":{"operationId":"social_read_tiktok_live_ranking","summary":"Public social tiktok_live_ranking","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"room_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Live room id."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."}},"required":["room_id","user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_daily_rank":{"post":{"operationId":"social_read_tiktok_live_daily_rank","summary":"Public social tiktok_live_daily_rank","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"room_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Live room id."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."}},"required":["room_id","user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_recommended":{"post":{"operationId":"social_read_tiktok_live_recommended","summary":"Public social tiktok_live_recommended","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"tag":{"type":"string","minLength":1,"maxLength":64,"description":"A live tag or game name (VALORANT, Music …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["tag"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_live_products":{"post":{"operationId":"social_read_tiktok_live_products","summary":"Public social tiktok_live_products","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"room_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Live room id."},"user_id":{"type":"string","pattern":"^[0-9]{1,30}$","maxLength":30,"description":"Numeric account id."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["room_id","user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_fake_views":{"post":{"operationId":"social_read_tiktok_fake_views","summary":"Public social tiktok_fake_views","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public TikTok video or photo URL."},"video_id":{"type":"string","pattern":"^[0-9]{5,30}$","maxLength":30,"description":"TikTok video id (the number in /video/<id>)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_comment_keywords":{"post":{"operationId":"social_read_tiktok_comment_keywords","summary":"Public social tiktok_comment_keywords","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public TikTok video or photo URL."},"video_id":{"type":"string","pattern":"^[0-9]{5,30}$","maxLength":30,"description":"TikTok video id (the number in /video/<id>)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_hot":{"post":{"operationId":"social_read_tiktok_shop_hot","summary":"Public social tiktok_shop_hot","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"region":{"type":"string","enum":["ID","JP","MX","MY","PH","SG","TH","VN"],"description":"A TikTok Shop region with a hot list."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["region"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_product":{"post":{"operationId":"social_read_tiktok_shop_product","summary":"Public social tiktok_shop_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"product_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"TikTok Shop product id."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."}},"required":["product_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_suggestions":{"post":{"operationId":"social_read_tiktok_shop_suggestions","summary":"Public social tiktok_shop_suggestions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_lives":{"post":{"operationId":"social_read_youtube_lives","summary":"Public social youtube_lives","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"YouTube channel id (UC…)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["channel_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_playlists":{"post":{"operationId":"social_read_youtube_playlists","summary":"Public social youtube_playlists","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"Public handle, with or without @."},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"YouTube channel id (UC…)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["handle"]},{"required":["channel_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_playlist":{"post":{"operationId":"social_read_youtube_playlist","summary":"Public social youtube_playlist","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"playlist_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{10,64}$","maxLength":64,"description":"YouTube playlist id (list=…)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["playlist_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_trending_shorts":{"post":{"operationId":"social_read_youtube_trending_shorts","summary":"Public social youtube_trending_shorts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_hashtag":{"post":{"operationId":"social_read_youtube_hashtag","summary":"Public social youtube_hashtag","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hashtag":{"type":"string","minLength":1,"maxLength":100,"description":"Hashtag, with or without #."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["hashtag"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_sponsors":{"post":{"operationId":"social_read_youtube_sponsors","summary":"Public social youtube_sponsors","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public YouTube video or Short URL."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/youtube_channel_search":{"post":{"operationId":"social_read_youtube_channel_search","summary":"Public social youtube_channel_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","maxLength":24,"description":"YouTube channel id (UC…)."},"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["channel_id","query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_profile":{"post":{"operationId":"social_read_x_profile","summary":"Public social x_profile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","maxLength":16,"description":"X handle, with or without @."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_posts":{"post":{"operationId":"social_read_x_posts","summary":"Public social x_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","maxLength":16,"description":"X handle, with or without @."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_media":{"post":{"operationId":"social_read_x_media","summary":"Public social x_media","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","maxLength":16,"description":"X handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_replies":{"post":{"operationId":"social_read_x_replies","summary":"Public social x_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","maxLength":16,"description":"X handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_post":{"post":{"operationId":"social_read_x_post","summary":"Public social x_post","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public X post URL (x.com/<user>/status/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_thread":{"post":{"operationId":"social_read_x_thread","summary":"Public social x_thread","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public X post URL (x.com/<user>/status/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_article":{"post":{"operationId":"social_read_x_article","summary":"Public social x_article","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public X article or post URL."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_transcript":{"post":{"operationId":"social_read_x_transcript","summary":"Public social x_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public X post URL (x.com/<user>/status/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_comments":{"post":{"operationId":"social_read_x_comments","summary":"Public social x_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public X post URL (x.com/<user>/status/<id>)."},"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"X post id (the number in /status/<id>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["post_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_reposters":{"post":{"operationId":"social_read_x_reposters","summary":"Public social x_reposters","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public X post URL (x.com/<user>/status/<id>)."},"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"X post id (the number in /status/<id>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["post_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_followers":{"post":{"operationId":"social_read_x_followers","summary":"Public social x_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","maxLength":16,"description":"X handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_following":{"post":{"operationId":"social_read_x_following","summary":"Public social x_following","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","maxLength":16,"description":"X handle, with or without @."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_search":{"post":{"operationId":"social_read_x_search","summary":"Public social x_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"sort":{"type":"string","enum":["Top","Latest","Media"],"description":"Top (default), Latest or Media."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_search_users":{"post":{"operationId":"social_read_x_search_users","summary":"Public social x_search_users","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_search_communities":{"post":{"operationId":"social_read_x_search_communities","summary":"Public social x_search_communities","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_trends":{"post":{"operationId":"social_read_x_trends","summary":"Public social x_trends","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"country":{"type":"string","pattern":"^[A-Za-z]{2,40}$","maxLength":40,"default":"UnitedStates","description":"Country name without spaces (UnitedStates, Japan, Korea …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_community":{"post":{"operationId":"social_read_x_community","summary":"Public social x_community","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"X community URL (x.com/i/communities/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/x_community_posts":{"post":{"operationId":"social_read_x_community_posts","summary":"Public social x_community_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"X community URL (x.com/i/communities/<id>)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_profile":{"post":{"operationId":"social_read_linkedin_profile","summary":"Public social linkedin_profile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Member profile URL (linkedin.com/in/<name>)."},"handle":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,99}$","maxLength":100,"description":"The name in the profile URL (linkedin.com/in/<name>)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_company":{"post":{"operationId":"social_read_linkedin_company","summary":"Public social linkedin_company","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Company page URL (linkedin.com/company/<name>)."},"handle":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,99}$","maxLength":100,"description":"The name in the company URL (linkedin.com/company/<name>)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_company_posts":{"post":{"operationId":"social_read_linkedin_company_posts","summary":"Public social linkedin_company_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Company page URL (linkedin.com/company/<name>)."},"handle":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,99}$","maxLength":100,"description":"The name in the company URL (linkedin.com/company/<name>)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_posts":{"post":{"operationId":"social_read_linkedin_posts","summary":"Public social linkedin_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Member profile URL (linkedin.com/in/<name>)."},"handle":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,99}$","maxLength":100,"description":"The name in the profile URL (linkedin.com/in/<name>)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_post":{"post":{"operationId":"social_read_linkedin_post","summary":"Public social linkedin_post","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public LinkedIn post URL."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_transcript":{"post":{"operationId":"social_read_linkedin_transcript","summary":"Public social linkedin_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public LinkedIn post URL."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_comments":{"post":{"operationId":"social_read_linkedin_comments","summary":"Public social linkedin_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public LinkedIn post URL."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_comment_replies":{"post":{"operationId":"social_read_linkedin_comment_replies","summary":"Public social linkedin_comment_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"The comment's URL (from a comments read)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_reactions":{"post":{"operationId":"social_read_linkedin_reactions","summary":"Public social linkedin_reactions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public LinkedIn post URL."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_member_comments":{"post":{"operationId":"social_read_linkedin_member_comments","summary":"Public social linkedin_member_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Member profile URL (linkedin.com/in/<name>)."},"handle":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,99}$","maxLength":100,"description":"The name in the profile URL (linkedin.com/in/<name>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_member_reactions":{"post":{"operationId":"social_read_linkedin_member_reactions","summary":"Public social linkedin_member_reactions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Member profile URL (linkedin.com/in/<name>)."},"handle":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,99}$","maxLength":100,"description":"The name in the profile URL (linkedin.com/in/<name>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_search_posts":{"post":{"operationId":"social_read_linkedin_search_posts","summary":"Public social linkedin_search_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"date_posted":{"type":"string","enum":["last-hour","last-day","last-week","last-month","last-year"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_search_companies":{"post":{"operationId":"social_read_linkedin_search_companies","summary":"Public social linkedin_search_companies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_search_groups":{"post":{"operationId":"social_read_linkedin_search_groups","summary":"Public social linkedin_search_groups","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_group":{"post":{"operationId":"social_read_linkedin_group","summary":"Public social linkedin_group","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Group URL (linkedin.com/groups/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_jobs":{"post":{"operationId":"social_read_linkedin_jobs","summary":"Public social linkedin_jobs","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"location":{"type":"string","minLength":1,"maxLength":100,"description":"A city, region or country (New York, Germany …)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_job":{"post":{"operationId":"social_read_linkedin_job","summary":"Public social linkedin_job","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Job posting URL (linkedin.com/jobs/view/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_profile":{"post":{"operationId":"social_read_reddit_profile","summary":"Public social reddit_profile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^(?:u/)?[A-Za-z0-9_-]{3,20}$","maxLength":22,"description":"Reddit username, with or without u/."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_user_trophies":{"post":{"operationId":"social_read_reddit_user_trophies","summary":"Public social reddit_user_trophies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^(?:u/)?[A-Za-z0-9_-]{3,20}$","maxLength":22,"description":"Reddit username, with or without u/."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_user_posts":{"post":{"operationId":"social_read_reddit_user_posts","summary":"Public social reddit_user_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^(?:u/)?[A-Za-z0-9_-]{3,20}$","maxLength":22,"description":"Reddit username, with or without u/."},"sort":{"type":"string","enum":["NEW","HOT","TOP"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_user_comments":{"post":{"operationId":"social_read_reddit_user_comments","summary":"Public social reddit_user_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^(?:u/)?[A-Za-z0-9_-]{3,20}$","maxLength":22,"description":"Reddit username, with or without u/."},"sort":{"type":"string","enum":["NEW","HOT","TOP"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_subreddit":{"post":{"operationId":"social_read_reddit_subreddit","summary":"Public social reddit_subreddit","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"subreddit":{"type":"string","pattern":"^(?:r/)?[A-Za-z0-9_]{2,21}$","maxLength":23,"description":"Subreddit name, with or without r/."}},"required":["subreddit"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_subreddit_posts":{"post":{"operationId":"social_read_reddit_subreddit_posts","summary":"Public social reddit_subreddit_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"subreddit":{"type":"string","pattern":"^(?:r/)?[A-Za-z0-9_]{2,21}$","maxLength":23,"description":"Subreddit name, with or without r/."},"sort":{"type":"string","enum":["best","hot","new","top","rising"]},"timeframe":{"type":"string","enum":["all","day","week","month","year"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["subreddit"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_subreddit_highlights":{"post":{"operationId":"social_read_reddit_subreddit_highlights","summary":"Public social reddit_subreddit_highlights","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"subreddit_id":{"type":"string","pattern":"^t5_[a-z0-9]{2,12}$","maxLength":15,"description":"Subreddit id (t5_…, from the subreddit read)."}},"required":["subreddit_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_post":{"post":{"operationId":"social_read_reddit_post","summary":"Public social reddit_post","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Reddit post URL (reddit.com/r/<sub>/comments/<id>/…)."},"post_id":{"type":"string","pattern":"^(?:t3_)?[a-z0-9]{4,12}$","maxLength":15,"description":"Reddit post id (the id after /comments/, with or without t3_)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["post_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_comments":{"post":{"operationId":"social_read_reddit_comments","summary":"Public social reddit_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Reddit post URL (reddit.com/r/<sub>/comments/<id>/…)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_transcript":{"post":{"operationId":"social_read_reddit_transcript","summary":"Public social reddit_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Reddit post URL (reddit.com/r/<sub>/comments/<id>/…)."},"language":{"type":"string","pattern":"^[A-Za-z-]{2,10}$","maxLength":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_search":{"post":{"operationId":"social_read_reddit_search","summary":"Public social reddit_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"sort":{"type":"string","enum":["relevance","new","top","comment_count"]},"timeframe":{"type":"string","enum":["all","day","week","month","year"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_search_subreddit":{"post":{"operationId":"social_read_reddit_search_subreddit","summary":"Public social reddit_search_subreddit","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"subreddit":{"type":"string","pattern":"^(?:r/)?[A-Za-z0-9_]{2,21}$","maxLength":23,"description":"Subreddit name, with or without r/."},"query":{"type":"string","minLength":1,"maxLength":256},"sort":{"type":"string","enum":["relevance","new","top","comment_count"]},"timeframe":{"type":"string","enum":["all","day","week","month","year"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["subreddit","query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_suggestions":{"post":{"operationId":"social_read_reddit_suggestions","summary":"Public social reddit_suggestions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_popular":{"post":{"operationId":"social_read_reddit_popular","summary":"Public social reddit_popular","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sort":{"type":"string","enum":["HOT","NEW","TOP","RISING"]},"time":{"type":"string","enum":["HOUR","DAY","WEEK","MONTH","YEAR","ALL"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_news":{"post":{"operationId":"social_read_reddit_news","summary":"Public social reddit_news","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_games":{"post":{"operationId":"social_read_reddit_games","summary":"Public social reddit_games","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_home":{"post":{"operationId":"social_read_reddit_home","summary":"Public social reddit_home","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/reddit_trending_searches":{"post":{"operationId":"social_read_reddit_trending_searches","summary":"Public social reddit_trending_searches","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_profile":{"post":{"operationId":"social_read_douyin_profile","summary":"Public social douyin_profile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sec_user_id":{"type":"string","pattern":"^MS4wLjABAAAA[A-Za-z0-9_-]{10,120}$","maxLength":140,"description":"Douyin sec_user_id (MS4wLjABAAAA…)."}},"required":["sec_user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_profile_by_id":{"post":{"operationId":"social_read_douyin_profile_by_id","summary":"Public social douyin_profile_by_id","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin numeric user id (uid)."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_videos":{"post":{"operationId":"social_read_douyin_videos","summary":"Public social douyin_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sec_user_id":{"type":"string","pattern":"^MS4wLjABAAAA[A-Za-z0-9_-]{10,120}$","maxLength":140,"description":"Douyin sec_user_id (MS4wLjABAAAA…)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["sec_user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_followers":{"post":{"operationId":"social_read_douyin_followers","summary":"Public social douyin_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sec_user_id":{"type":"string","pattern":"^MS4wLjABAAAA[A-Za-z0-9_-]{10,120}$","maxLength":140,"description":"Douyin sec_user_id (MS4wLjABAAAA…)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["sec_user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_following":{"post":{"operationId":"social_read_douyin_following","summary":"Public social douyin_following","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sec_user_id":{"type":"string","pattern":"^MS4wLjABAAAA[A-Za-z0-9_-]{10,120}$","maxLength":140,"description":"Douyin sec_user_id (MS4wLjABAAAA…)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["sec_user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_video":{"post":{"operationId":"social_read_douyin_video","summary":"Public social douyin_video","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Douyin video URL (douyin.com/video/<id>)."},"video_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin video id (aweme_id)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_comments":{"post":{"operationId":"social_read_douyin_comments","summary":"Public social douyin_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Douyin video URL (douyin.com/video/<id>)."},"video_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin video id (aweme_id)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_comment_replies":{"post":{"operationId":"social_read_douyin_comment_replies","summary":"Public social douyin_comment_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Douyin video URL (douyin.com/video/<id>)."},"video_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin video id (aweme_id)."},"comment_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"The comment whose replies to read."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["comment_id"],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_danmaku":{"post":{"operationId":"social_read_douyin_danmaku","summary":"Public social douyin_danmaku","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Douyin video URL (douyin.com/video/<id>)."},"video_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin video id (aweme_id)."},"duration_ms":{"type":"integer","minimum":1,"maximum":36000000,"description":"The video's length in ms (video.duration from a video read)."},"start_ms":{"type":"integer","minimum":0,"maximum":36000000},"end_ms":{"type":"integer","minimum":1,"maximum":36000000}},"required":["duration_ms"],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_related":{"post":{"operationId":"social_read_douyin_related","summary":"Public social douyin_related","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Douyin video URL (douyin.com/video/<id>)."},"video_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin video id (aweme_id)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["video_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_video_stats":{"post":{"operationId":"social_read_douyin_video_stats","summary":"Public social douyin_video_stats","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"video_ids":{"type":"string","pattern":"^[0-9]{5,30}(,[0-9]{5,30}){0,19}$","maxLength":640,"description":"Up to 20 video ids, comma-separated."}},"required":["video_ids"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_mix":{"post":{"operationId":"social_read_douyin_mix","summary":"Public social douyin_mix","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mix_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Video collection (mix) id."}},"required":["mix_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_mix_videos":{"post":{"operationId":"social_read_douyin_mix_videos","summary":"Public social douyin_mix_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mix_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Video collection (mix) id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["mix_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_sound":{"post":{"operationId":"social_read_douyin_sound","summary":"Public social douyin_sound","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sound_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin sound (music) id."}},"required":["sound_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_sound_videos":{"post":{"operationId":"social_read_douyin_sound_videos","summary":"Public social douyin_sound_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sound_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin sound (music) id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["sound_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hashtag":{"post":{"operationId":"social_read_douyin_hashtag","summary":"Public social douyin_hashtag","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hashtag_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin hashtag (challenge) id."}},"required":["hashtag_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hashtag_videos":{"post":{"operationId":"social_read_douyin_hashtag_videos","summary":"Public social douyin_hashtag_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hashtag_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin hashtag (challenge) id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["hashtag_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_search_users":{"post":{"operationId":"social_read_douyin_search_users","summary":"Public social douyin_search_users","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_search_videos":{"post":{"operationId":"social_read_douyin_search_videos","summary":"Public social douyin_search_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_search_hashtags":{"post":{"operationId":"social_read_douyin_search_hashtags","summary":"Public social douyin_search_hashtags","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_search_music":{"post":{"operationId":"social_read_douyin_search_music","summary":"Public social douyin_search_music","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_search_images":{"post":{"operationId":"social_read_douyin_search_images","summary":"Public social douyin_search_images","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_suggestions":{"post":{"operationId":"social_read_douyin_suggestions","summary":"Public social douyin_suggestions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_search":{"post":{"operationId":"social_read_douyin_hot_search","summary":"Public social douyin_hot_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_challenges":{"post":{"operationId":"social_read_douyin_hot_challenges","summary":"Public social douyin_hot_challenges","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_spots":{"post":{"operationId":"social_read_douyin_hot_spots","summary":"Public social douyin_hot_spots","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_music":{"post":{"operationId":"social_read_douyin_hot_music","summary":"Public social douyin_hot_music","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_props":{"post":{"operationId":"social_read_douyin_hot_props","summary":"Public social douyin_hot_props","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_topics":{"post":{"operationId":"social_read_douyin_hot_topics","summary":"Public social douyin_hot_topics","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_videos":{"post":{"operationId":"social_read_douyin_hot_videos","summary":"Public social douyin_hot_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_hot_words":{"post":{"operationId":"social_read_douyin_hot_words","summary":"Public social douyin_hot_words","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_rising_topics":{"post":{"operationId":"social_read_douyin_rising_topics","summary":"Public social douyin_rising_topics","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_brand_hot":{"post":{"operationId":"social_read_douyin_brand_hot","summary":"Public social douyin_brand_hot","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_materials":{"post":{"operationId":"social_read_douyin_materials","summary":"Public social douyin_materials","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_home":{"post":{"operationId":"social_read_douyin_home","summary":"Public social douyin_home","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_channel":{"post":{"operationId":"social_read_douyin_channel","summary":"Public social douyin_channel","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"channel_id":{"type":"integer","minimum":1,"maximum":99999999,"description":"Douyin channel tag id (300203 by default)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_live_gifts":{"post":{"operationId":"social_read_douyin_live_gifts","summary":"Public social douyin_live_gifts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"room_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin live room id."}},"required":["room_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_profile":{"post":{"operationId":"social_read_facebook_profile","summary":"Public social facebook_profile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook page or profile URL."},"handle":{"type":"string","pattern":"^[A-Za-z0-9.]{2,80}$","maxLength":80,"description":"The name in the page URL (facebook.com/<name>)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_posts":{"post":{"operationId":"social_read_facebook_posts","summary":"Public social facebook_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook page or profile URL."},"handle":{"type":"string","pattern":"^[A-Za-z0-9.]{2,80}$","maxLength":80,"description":"The name in the page URL (facebook.com/<name>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_reels":{"post":{"operationId":"social_read_facebook_reels","summary":"Public social facebook_reels","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook page or profile URL."},"handle":{"type":"string","pattern":"^[A-Za-z0-9.]{2,80}$","maxLength":80,"description":"The name in the page URL (facebook.com/<name>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_photos":{"post":{"operationId":"social_read_facebook_photos","summary":"Public social facebook_photos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook page or profile URL."},"handle":{"type":"string","pattern":"^[A-Za-z0-9.]{2,80}$","maxLength":80,"description":"The name in the page URL (facebook.com/<name>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_page_events":{"post":{"operationId":"social_read_facebook_page_events","summary":"Public social facebook_page_events","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook page or profile URL."},"handle":{"type":"string","pattern":"^[A-Za-z0-9.]{2,80}$","maxLength":80,"description":"The name in the page URL (facebook.com/<name>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["handle"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_post":{"post":{"operationId":"social_read_facebook_post","summary":"Public social facebook_post","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook post, reel or video URL."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_transcript":{"post":{"operationId":"social_read_facebook_transcript","summary":"Public social facebook_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook post, reel or video URL."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_comments":{"post":{"operationId":"social_read_facebook_comments","summary":"Public social facebook_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook post, reel or video URL."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_comment_replies":{"post":{"operationId":"social_read_facebook_comment_replies","summary":"Public social facebook_comment_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"feedback_id":{"type":"string","pattern":"^[A-Za-z0-9=_-]{8,512}$","maxLength":512,"description":"The comment's feedback_id (from a comments read)."},"expansion_token":{"type":"string","minLength":1,"maxLength":1024,"description":"The comment's replies expansion_token."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["feedback_id","expansion_token"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_group":{"post":{"operationId":"social_read_facebook_group","summary":"Public social facebook_group","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook group URL."},"group_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Facebook group id."}},"required":[],"anyOf":[{"required":["url"]},{"required":["group_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_group_posts":{"post":{"operationId":"social_read_facebook_group_posts","summary":"Public social facebook_group_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Public Facebook group URL."},"group_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Facebook group id."},"sort":{"type":"string","enum":["TOP_POSTS","RECENT_ACTIVITY","CHRONOLOGICAL"]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["url"]},{"required":["group_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_event":{"post":{"operationId":"social_read_facebook_event","summary":"Public social facebook_event","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Facebook event URL."},"event_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Facebook event id."}},"required":[],"anyOf":[{"required":["url"]},{"required":["event_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_search_events":{"post":{"operationId":"social_read_facebook_search_events","summary":"Public social facebook_search_events","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_city_events":{"post":{"operationId":"social_read_facebook_city_events","summary":"Public social facebook_city_events","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"A city's events URL (facebook.com/events/explore/<city>/<id>)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_search_posts":{"post":{"operationId":"social_read_facebook_search_posts","summary":"Public social facebook_search_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_marketplace":{"post":{"operationId":"social_read_facebook_marketplace","summary":"Public social facebook_marketplace","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"lat":{"type":"string","pattern":"^-?[0-9]{1,2}(\\.[0-9]{1,7})?$","maxLength":12,"description":"Latitude of the area to search (from a locations read)."},"lng":{"type":"string","pattern":"^-?[0-9]{1,3}(\\.[0-9]{1,7})?$","maxLength":13,"description":"Longitude of the area to search."},"radius_km":{"type":"integer","minimum":1,"maximum":500},"min_price":{"type":"integer","minimum":0,"maximum":100000000},"max_price":{"type":"integer","minimum":0,"maximum":100000000},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query","lat","lng"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_marketplace_item":{"post":{"operationId":"social_read_facebook_marketplace_item","summary":"Public social facebook_marketplace_item","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Marketplace listing URL."},"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Marketplace listing id."}},"required":[],"anyOf":[{"required":["url"]},{"required":["item_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/facebook_marketplace_locations":{"post":{"operationId":"social_read_facebook_marketplace_locations","summary":"Public social facebook_marketplace_locations","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_profile":{"post":{"operationId":"social_read_weibo_profile","summary":"Public social weibo_profile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_posts":{"post":{"operationId":"social_read_weibo_posts","summary":"Public social weibo_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_videos":{"post":{"operationId":"social_read_weibo_videos","summary":"Public social weibo_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_photos":{"post":{"operationId":"social_read_weibo_photos","summary":"Public social weibo_photos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_articles":{"post":{"operationId":"social_read_weibo_articles","summary":"Public social weibo_articles","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_super_topics":{"post":{"operationId":"social_read_weibo_super_topics","summary":"Public social weibo_super_topics","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_collections":{"post":{"operationId":"social_read_weibo_collections","summary":"Public social weibo_collections","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_collection":{"post":{"operationId":"social_read_weibo_collection","summary":"Public social weibo_collection","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"collection_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Video collection id (from the collections read)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["collection_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_post":{"post":{"operationId":"social_read_weibo_post","summary":"Public social weibo_post","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo post id (mid)."}},"required":["post_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_video":{"post":{"operationId":"social_read_weibo_video","summary":"Public social weibo_video","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo post id (mid)."}},"required":["post_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_comments":{"post":{"operationId":"social_read_weibo_comments","summary":"Public social weibo_comments","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo post id (mid)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["post_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_comment_replies":{"post":{"operationId":"social_read_weibo_comment_replies","summary":"Public social weibo_comment_replies","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"comment_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"The comment whose replies to read."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["comment_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_likers":{"post":{"operationId":"social_read_weibo_likers","summary":"Public social weibo_likers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo post id (mid)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["post_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_reposts":{"post":{"operationId":"social_read_weibo_reposts","summary":"Public social weibo_reposts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"post_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo post id (mid)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["post_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_followers":{"post":{"operationId":"social_read_weibo_followers","summary":"Public social weibo_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_following":{"post":{"operationId":"social_read_weibo_following","summary":"Public social weibo_following","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uid":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Weibo user id (uid, from a user search or profile)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["uid"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search":{"post":{"operationId":"social_read_weibo_search","summary":"Public social weibo_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search_users":{"post":{"operationId":"social_read_weibo_search_users","summary":"Public social weibo_search_users","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search_topics":{"post":{"operationId":"social_read_weibo_search_topics","summary":"Public social weibo_search_topics","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search_videos":{"post":{"operationId":"social_read_weibo_search_videos","summary":"Public social weibo_search_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"sort":{"type":"string","enum":["hot","new"]},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search_images":{"post":{"operationId":"social_read_weibo_search_images","summary":"Public social weibo_search_images","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search_related":{"post":{"operationId":"social_read_weibo_search_related","summary":"Public social weibo_search_related","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_search_ai":{"post":{"operationId":"social_read_weibo_search_ai","summary":"Public social weibo_search_ai","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_hot_search":{"post":{"operationId":"social_read_weibo_hot_search","summary":"Public social weibo_hot_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_social_ranking":{"post":{"operationId":"social_read_weibo_social_ranking","summary":"Public social weibo_social_ranking","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_entertainment_ranking":{"post":{"operationId":"social_read_weibo_entertainment_ranking","summary":"Public social weibo_entertainment_ranking","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_life_ranking":{"post":{"operationId":"social_read_weibo_life_ranking","summary":"Public social weibo_life_ranking","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_hot_posts":{"post":{"operationId":"social_read_weibo_hot_posts","summary":"Public social weibo_hot_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"period":{"type":"string","enum":["hour","day","week"],"description":"hour (default), day or week."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_recommended":{"post":{"operationId":"social_read_weibo_recommended","summary":"Public social weibo_recommended","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/weibo_featured_videos":{"post":{"operationId":"social_read_weibo_featured_videos","summary":"Public social weibo_featured_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ads":{"post":{"operationId":"social_read_tiktok_ads","summary":"Public social tiktok_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"period":{"type":"integer","enum":[7,30,180]},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ad":{"post":{"operationId":"social_read_tiktok_ad","summary":"Public social tiktok_ad","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"TikTok ad id from an ads read."}},"required":["ad_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_top_ads":{"post":{"operationId":"social_read_tiktok_top_ads","summary":"Public social tiktok_top_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"period":{"type":"integer","enum":[7,30,180]},"page":{"type":"integer","minimum":1,"maximum":20},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ad_transparency":{"post":{"operationId":"social_read_tiktok_ad_transparency","summary":"Public social tiktok_ad_transparency","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ads":{"post":{"operationId":"social_read_meta_ads","summary":"Public social meta_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"country":{"type":"string","pattern":"^(ALL|[A-Za-z]{2})$","maxLength":3,"description":"Two-letter country the ads ran in, or ALL (default)."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","ALL"]},"media_type":{"type":"string","enum":["ALL","IMAGE","VIDEO","MEME","NONE"]},"sort":{"type":"string","enum":["total_impressions","relevancy_monthly_grouped"]},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_page_ads":{"post":{"operationId":"social_read_meta_page_ads","summary":"Public social meta_page_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"page_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Facebook Page id (from a meta pages read)."},"company":{"type":"string","minLength":1,"maxLength":120,"description":"Advertiser name, when the Page id is unknown."},"country":{"type":"string","pattern":"^(ALL|[A-Za-z]{2})$","maxLength":3,"description":"Two-letter country the ads ran in, or ALL (default)."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","ALL"]},"media_type":{"type":"string","enum":["ALL","IMAGE","VIDEO","MEME","NONE"]},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["page_id"]},{"required":["company"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ad":{"post":{"operationId":"social_read_meta_ad","summary":"Public social meta_ad","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Meta Ad Library ad URL (facebook.com/ads/library/?id=…)."},"ad_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Meta Ad Library id (ad_archive_id)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["ad_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ad_transcript":{"post":{"operationId":"social_read_meta_ad_transcript","summary":"Public social meta_ad_transcript","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Meta Ad Library ad URL (facebook.com/ads/library/?id=…)."},"ad_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Meta Ad Library id (ad_archive_id)."}},"required":[],"anyOf":[{"required":["url"]},{"required":["ad_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_political_ads":{"post":{"operationId":"social_read_meta_political_ads","summary":"Public social meta_political_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2,"description":"Two-letter country the ads reached (US, GB …)."},"query":{"type":"string","minLength":1,"maxLength":256,"description":"Words in the ads (optional)."},"since":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["country"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_eu_reach":{"post":{"operationId":"social_read_meta_eu_reach","summary":"Public social meta_eu_reach","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2,"description":"An EU/EEA country (DE, FR …): the reach data exists only there."},"query":{"type":"string","minLength":1,"maxLength":256,"description":"Words in the ads (optional)."},"page_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Scope to one advertiser's Facebook Page id."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["country"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_domain_ads":{"post":{"operationId":"social_read_meta_domain_ads","summary":"Public social meta_domain_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"domain":{"type":"string","pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$","maxLength":253,"description":"The advertiser's website domain (nike.com)."},"country":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2,"description":"Two-letter country the ads ran in."},"status":{"type":"string","enum":["inactive","all"],"description":"Active ads by default; inactive or all."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["domain"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_advertisers":{"post":{"operationId":"social_read_meta_advertisers","summary":"Public social meta_advertisers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_advertisers":{"post":{"operationId":"social_read_google_advertisers","summary":"Public social google_advertisers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads":{"post":{"operationId":"social_read_google_ads","summary":"Public social google_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"domain":{"type":"string","pattern":"^[A-Za-z0-9.-]{3,253}$","maxLength":253,"description":"The advertiser's website domain (lululemon.com)."},"advertiser_id":{"type":"string","pattern":"^AR[0-9]{10,30}$","maxLength":32,"description":"Google advertiser id (AR…, from an advertisers read)."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"platform":{"type":"string","enum":["search","youtube","maps","shopping","play"]},"format":{"type":"string","enum":["text","image","video"]},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["domain"]},{"required":["advertiser_id"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ad":{"post":{"operationId":"social_read_google_ad","summary":"Public social google_ad","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Ads Transparency ad URL (adstransparency.google.com/advertiser/…/creative/…)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_domain_ads":{"post":{"operationId":"social_read_tiktok_domain_ads","summary":"Public social tiktok_domain_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"domain":{"type":"string","pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$","maxLength":253,"description":"The advertiser's website domain (gymshark.com)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["domain"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ad_analytics":{"post":{"operationId":"social_read_tiktok_ad_analytics","summary":"Public social tiktok_ad_analytics","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok Creative Center ad id (id from a top-ads or spotlight read)."},"metric":{"type":"string","enum":["remain","click","convert"],"description":"remain (default), click or convert."}},"required":["ad_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ad_keyframes":{"post":{"operationId":"social_read_tiktok_ad_keyframes","summary":"Public social tiktok_ad_keyframes","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok Creative Center ad id (id from a top-ads or spotlight read)."}},"required":["ad_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ad_percentile":{"post":{"operationId":"social_read_tiktok_ad_percentile","summary":"Public social tiktok_ad_percentile","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok Creative Center ad id (id from a top-ads or spotlight read)."},"metric":{"type":"string","enum":["ctr_percentile","cvr_percentile","show_cnt_percentile","like_percentile"],"description":"Which percentile (ctr_percentile by default)."}},"required":["ad_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ads_spotlight":{"post":{"operationId":"social_read_tiktok_ads_spotlight","summary":"Public social tiktok_ads_spotlight","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"industry":{"type":"string","pattern":"^[0-9]{6,15}$","maxLength":15,"description":"Creative Center industry id (from an ads read)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_ads":{"post":{"operationId":"social_read_linkedin_ads","summary":"Public social linkedin_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"company":{"type":"string","minLength":1,"maxLength":120,"description":"Advertiser company name."},"query":{"type":"string","minLength":1,"maxLength":256},"countries":{"type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2}){0,19}$","maxLength":59,"description":"Comma-separated country codes (US,CA)."},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"YYYY-MM-DD."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[],"anyOf":[{"required":["company"]},{"required":["query"]}]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/linkedin_ad":{"post":{"operationId":"social_read_linkedin_ad","summary":"Public social linkedin_ad","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"LinkedIn Ad Library ad URL (linkedin.com/ad-library/detail/<id>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_search":{"post":{"operationId":"social_read_amazon_search","summary":"Public social amazon_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"country":{"type":"string","enum":["US","AU","BR","CA","CN","FR","DE","IN","IT","MX","NL","SG","ES","TR","AE","GB","JP","SA","PL","SE","BE","EG","ZA","IE"],"description":"Amazon marketplace (default US)."},"sort":{"type":"string","enum":["RELEVANCE","LOWEST_PRICE","HIGHEST_PRICE","REVIEWS","NEWEST","BEST_SELLERS"],"description":"RELEVANCE (default), LOWEST_PRICE, HIGHEST_PRICE, REVIEWS, NEWEST or BEST_SELLERS."},"prime":{"type":"string","enum":["true","false"],"description":"true: Prime-eligible only."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_product":{"post":{"operationId":"social_read_amazon_product","summary":"Public social amazon_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"asin":{"type":"string","pattern":"^[A-Z0-9]{10}$","maxLength":10,"description":"Amazon ASIN (10 characters)."},"country":{"type":"string","enum":["US","AU","BR","CA","CN","FR","DE","IN","IT","MX","NL","SG","ES","TR","AE","GB","JP","SA","PL","SE","BE","EG","ZA","IE"],"description":"Amazon marketplace (default US)."}},"required":["asin"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_reviews":{"post":{"operationId":"social_read_amazon_reviews","summary":"Public social amazon_reviews","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"asin":{"type":"string","pattern":"^[A-Z0-9]{10}$","maxLength":10,"description":"Amazon ASIN (10 characters)."},"country":{"type":"string","enum":["US","AU","BR","CA","CN","FR","DE","IN","IT","MX","NL","SG","ES","TR","AE","GB","JP","SA","PL","SE","BE","EG","ZA","IE"],"description":"Amazon marketplace (default US)."}},"required":["asin"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_best_sellers":{"post":{"operationId":"social_read_amazon_best_sellers","summary":"Public social amazon_best_sellers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","pattern":"^[A-Za-z0-9_/-]{1,120}$","maxLength":120,"description":"Best Sellers category path from its URL (electronics, kitchen/289814)."},"country":{"type":"string","enum":["US","AU","BR","CA","CN","FR","DE","IN","IT","MX","NL","SG","ES","TR","AE","GB","JP","SA","PL","SE","BE","EG","ZA","IE"],"description":"Amazon marketplace (default US)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["category"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_category":{"post":{"operationId":"social_read_amazon_category","summary":"Public social amazon_category","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Category node id (the node= value of its URL)."},"country":{"type":"string","enum":["US","AU","BR","CA","CN","FR","DE","IN","IT","MX","NL","SG","ES","TR","AE","GB","JP","SA","PL","SE","BE","EG","ZA","IE"],"description":"Amazon marketplace (default US)."},"sort":{"type":"string","enum":["RELEVANCE","LOWEST_PRICE","HIGHEST_PRICE","REVIEWS","NEWEST","BEST_SELLERS"],"description":"RELEVANCE (default), LOWEST_PRICE, HIGHEST_PRICE, REVIEWS, NEWEST or BEST_SELLERS."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."}},"required":["category_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_sellers":{"post":{"operationId":"social_read_amazon_sellers","summary":"Public social amazon_sellers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"asin":{"type":"string","pattern":"^[A-Z0-9]{10}$","maxLength":10,"description":"Amazon ASIN (10 characters)."},"location_code":{"type":"integer","minimum":2000,"maximum":9999999,"description":"Location code (2840 = United States, 2826 = United Kingdom)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["asin"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_variations":{"post":{"operationId":"social_read_amazon_variations","summary":"Public social amazon_variations","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"asin":{"type":"string","pattern":"^[A-Z0-9]{10}$","maxLength":10,"description":"Amazon ASIN (10 characters)."},"location_code":{"type":"integer","minimum":2000,"maximum":9999999,"description":"Location code (2840 = United States, 2826 = United Kingdom)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["asin"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/amazon_store":{"post":{"operationId":"social_read_amazon_store","summary":"Public social amazon_store","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Amazon storefront URL (amazon.com/shop/<name>)."}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/taobao_search":{"post":{"operationId":"social_read_taobao_search","summary":"Public social taobao_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"sort":{"type":"string","enum":["_sale","_bid","bid","_coefp"],"description":"_sale (sales), _bid (price high→low), bid (price low→high) or _coefp."},"tmall":{"type":"string","enum":["true","false"],"description":"true: Tmall stores only."},"min_price":{"type":"string","pattern":"^[0-9.]{1,12}$","maxLength":12},"max_price":{"type":"string","pattern":"^[0-9.]{1,12}$","maxLength":12},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/taobao_product":{"post":{"operationId":"social_read_taobao_product","summary":"Public social taobao_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/taobao_store":{"post":{"operationId":"social_read_taobao_store","summary":"Public social taobao_store","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"seller_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Seller (shop owner) id."},"sort":{"type":"string","enum":["_sale","_default"],"description":"_sale (by sales) or _default."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["seller_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/taobao_reviews":{"post":{"operationId":"social_read_taobao_reviews","summary":"Public social taobao_reviews","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."},"sort":{"type":"string","enum":["feedbackdate","general"],"description":"feedbackdate (newest) or general."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/taobao_buyer_posts":{"post":{"operationId":"social_read_taobao_buyer_posts","summary":"Public social taobao_buyer_posts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/jd_search":{"post":{"operationId":"social_read_jd_search","summary":"Public social jd_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/jd_top_sellers":{"post":{"operationId":"social_read_jd_top_sellers","summary":"Public social jd_top_sellers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/jd_product":{"post":{"operationId":"social_read_jd_product","summary":"Public social jd_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/jd_price":{"post":{"operationId":"social_read_jd_price","summary":"Public social jd_price","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/jd_reviews":{"post":{"operationId":"social_read_jd_reviews","summary":"Public social jd_reviews","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/jd_store":{"post":{"operationId":"social_read_jd_store","summary":"Public social jd_store","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"shop_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"JD shop id."},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."}},"required":["shop_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_search":{"post":{"operationId":"social_read_tiktok_shop_search","summary":"Public social tiktok_shop_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"country":{"type":"string","enum":["US","VN","TH","PH","MY","ID","GB","SG","ES","MX","DE","IT","FR","BR","JP"],"description":"TikTok Shop market (default US)."},"limit":{"type":"integer","minimum":1,"maximum":10,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_reviews":{"post":{"operationId":"social_read_tiktok_shop_reviews","summary":"Public social tiktok_shop_reviews","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"TikTok Shop product URL (tiktok.com/shop/pdp/…)."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_categories":{"post":{"operationId":"social_read_tiktok_shop_categories","summary":"Public social tiktok_shop_categories","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_category":{"post":{"operationId":"social_read_tiktok_shop_category","summary":"Public social tiktok_shop_category","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok Shop category id (from kind categories)."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["category_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_creator":{"post":{"operationId":"social_read_tiktok_shop_creator","summary":"Public social tiktok_shop_creator","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"The creator's or shop's TikTok handle."},"region":{"type":"string","pattern":"^[a-z]{2}$","maxLength":2,"description":"Lowercase market code (us, gb …)."}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_showcase":{"post":{"operationId":"social_read_tiktok_shop_showcase","summary":"Public social tiktok_shop_showcase","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","maxLength":31,"description":"The TikTok handle whose showcase to read."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["handle"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_shop_store":{"post":{"operationId":"social_read_tiktok_shop_store","summary":"Public social tiktok_shop_store","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"TikTok Shop store URL (tiktok.com/shop/store/…)."},"sort":{"type":"string","enum":["top","new_releases"],"description":"top (default) or new_releases."},"region":{"type":"string","pattern":"^[A-Za-z]{2}$","maxLength":2,"description":"Two-letter country code (US, GB, KR …)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["url"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_shop_search":{"post":{"operationId":"social_read_douyin_shop_search","summary":"Public social douyin_shop_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_shop_product":{"post":{"operationId":"social_read_douyin_shop_product","summary":"Public social douyin_shop_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_shop_skus":{"post":{"operationId":"social_read_douyin_shop_skus","summary":"Public social douyin_shop_skus","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_shop_reviews":{"post":{"operationId":"social_read_douyin_shop_reviews","summary":"Public social douyin_shop_reviews","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/douyin_shop_store":{"post":{"operationId":"social_read_douyin_shop_store","summary":"Public social douyin_shop_store","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"shop_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Douyin shop id."},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["shop_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/walmart_search":{"post":{"operationId":"social_read_walmart_search","summary":"Public social walmart_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/walmart_product":{"post":{"operationId":"social_read_walmart_product","summary":"Public social walmart_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"product_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Walmart product id (the number in its URL)."}},"required":["product_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/ebay_search":{"post":{"operationId":"social_read_ebay_search","summary":"Public social ebay_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/ebay_product":{"post":{"operationId":"social_read_ebay_product","summary":"Public social ebay_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"product_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"eBay item id (the number in its URL)."}},"required":["product_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/homedepot_search":{"post":{"operationId":"social_read_homedepot_search","summary":"Public social homedepot_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"country":{"type":"string","enum":["us","ca"],"description":"us (default) or ca."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/alibaba_1688_search":{"post":{"operationId":"social_read_alibaba_1688_search","summary":"Public social alibaba_1688_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/alibaba_1688_product":{"post":{"operationId":"social_read_alibaba_1688_product","summary":"Public social alibaba_1688_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xianyu_search":{"post":{"operationId":"social_read_xianyu_search","summary":"Public social xianyu_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"sort":{"type":"string","enum":["active","recent","credit","price_asc","price_desc","price_drop","newest"],"description":"active (default), recent, credit, price_asc, price_desc, price_drop or newest."},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xianyu_product":{"post":{"operationId":"social_read_xianyu_product","summary":"Public social xianyu_product","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"item_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Product (item) id."}},"required":["item_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/lazada_search":{"post":{"operationId":"social_read_lazada_search","summary":"Public social lazada_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"region":{"type":"string","enum":["sg","my","vn","th","ph","id"],"description":"Lazada market: sg (default), my, vn, th, ph or id."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/beike_listings":{"post":{"operationId":"social_read_beike_listings","summary":"Public social beike_listings","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"city_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Beike city id (110000 is Beijing)."},"filter":{"type":"string","maxLength":200,"description":"Beike filter conditions (district, price, layout)."},"offset":{"type":"integer","minimum":0,"maximum":2000,"description":"0, 20, 40 …"},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["city_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/beike_listing":{"post":{"operationId":"social_read_beike_listing","summary":"Public social beike_listing","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"city_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Beike city id."},"house_code":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"The listing's house code."}},"required":["city_id","house_code"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/beike_communities":{"post":{"operationId":"social_read_beike_communities","summary":"Public social beike_communities","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"city_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Beike city id."},"filter":{"type":"string","maxLength":200,"description":"Beike filter conditions."},"offset":{"type":"integer","minimum":0,"maximum":2000,"description":"0, 20, 40 …"},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["city_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/dewu_search":{"post":{"operationId":"social_read_dewu_search","summary":"Public social dewu_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"string","pattern":"^[0-9]{1,3}$","maxLength":3,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["query"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_search":{"post":{"operationId":"social_read_xingtu_search","summary":"Public social xingtu_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"search_type":{"type":"string","enum":["NICKNAME","CONTENT"],"description":"NICKNAME (default) or CONTENT."},"sort":{"type":"string","enum":["DEFAULT","FANS"],"description":"DEFAULT or FANS (most followers first)."},"followers":{"type":"string","pattern":"^[0-9.]*[-,][0-9.]*$","maxLength":40,"description":"Follower range, min-max."},"price_type":{"type":"string","enum":["VIDEO_1_20S","VIDEO_21_60S","VIDEO_OVER_60S","CUSTOM_SHORT_DRAMA_EPISODE","NATURAL_PLAY_CPM","SHORT_LIVE_SEEDING_VIDEO","SHORT_LIVE_WARMUP_VIDEO","CELEBRITY_SHORT_LIVE_SEEDING","CELEBRITY_SHORT_LIVE_WARMUP","CELEBRITY_VIDEO","COLLECTION_VIDEO","DOUYIN_SHORT_VIDEO_CO_CREATION_MAIN_CREATOR","DOUYIN_SHORT_VIDEO_CO_CREATION_PARTICIPANT"],"description":"Which rate price filters on (VIDEO_1_20S, VIDEO_21_60S …)."},"price":{"type":"string","pattern":"^[0-9.]*[-,][0-9.]*$","maxLength":40,"description":"Rate range in RMB, min-max (with price_type)."},"industry":{"type":"string","minLength":1,"maxLength":60,"description":"Industry (FOOD_AND_BEVERAGE, BEAUTY_AND_COSMETICS, GAMES …)."},"gender":{"type":"string","enum":["MALE","FEMALE"]},"location":{"type":"string","minLength":1,"maxLength":60,"description":"Province or city names, comma-separated (Chinese)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_creator_id":{"post":{"operationId":"social_read_xingtu_creator_id","summary":"Public social xingtu_creator_id","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sec_user_id":{"type":"string","pattern":"^MS4wLjABAAAA[A-Za-z0-9_-]{10,120}$","maxLength":140,"description":"Douyin sec_user_id (MS4wLjABAAAA…)."}},"required":["sec_user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_creator":{"post":{"operationId":"social_read_xingtu_creator","summary":"Public social xingtu_creator","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"platform":{"type":"string","enum":["SHORT_VIDEO","LIVE_STREAMING","PICTURE_TEXT","SHORT_DRAMA"],"description":"SHORT_VIDEO (default), LIVE_STREAMING, PICTURE_TEXT or SHORT_DRAMA."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_rates":{"post":{"operationId":"social_read_xingtu_rates","summary":"Public social xingtu_rates","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"platform":{"type":"string","enum":["SHORT_VIDEO","LIVE_STREAMING","PICTURE_TEXT","SHORT_DRAMA"],"description":"SHORT_VIDEO (default), LIVE_STREAMING, PICTURE_TEXT or SHORT_DRAMA."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_audience":{"post":{"operationId":"social_read_xingtu_audience","summary":"Public social xingtu_audience","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"platform":{"type":"string","enum":["SHORT_VIDEO","LIVE_STREAMING","PICTURE_TEXT","SHORT_DRAMA"],"description":"SHORT_VIDEO (default), LIVE_STREAMING, PICTURE_TEXT or SHORT_DRAMA."},"link_type":{"type":"string","enum":["CONNECTED","AWARE","INTERESTED","LIKE","FOLLOW"],"description":"Which audience: CONNECTED (default), AWARE, INTERESTED, LIKE or FOLLOW."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_followers":{"post":{"operationId":"social_read_xingtu_followers","summary":"Public social xingtu_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"type":{"type":"string","enum":["FAN","DIE_HARD_FAN"],"description":"FAN (default) or DIE_HARD_FAN."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_follower_trend":{"post":{"operationId":"social_read_xingtu_follower_trend","summary":"Public social xingtu_follower_trend","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"First day, YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"Last day, YYYY-MM-DD."}},"required":["creator_id","start_date","end_date"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_cost":{"post":{"operationId":"social_read_xingtu_cost","summary":"Public social xingtu_cost","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_videos":{"post":{"operationId":"social_read_xingtu_videos","summary":"Public social xingtu_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"only_ordered":{"type":"string","enum":["true","false"],"description":"true: only videos brands ordered."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_keywords":{"post":{"operationId":"social_read_xingtu_keywords","summary":"Public social xingtu_keywords","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_comment_words":{"post":{"operationId":"social_read_xingtu_comment_words","summary":"Public social xingtu_comment_words","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"creator_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Xingtu creator id (from kind search or kind creator_id)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["creator_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_video_report":{"post":{"operationId":"social_read_xingtu_video_report","summary":"Public social xingtu_video_report","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"video_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Douyin video id of an ordered video."}},"required":["video_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_ranking_types":{"post":{"operationId":"social_read_xingtu_ranking_types","summary":"Public social xingtu_ranking_types","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_rankings":{"post":{"operationId":"social_read_xingtu_rankings","summary":"Public social xingtu_rankings","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"integer","minimum":1,"maximum":999999,"description":"Ranking code (from kind ranking_types)."},"qualifier":{"type":"string","minLength":1,"maxLength":64,"description":"Category qualifier id from kind ranking_types (1901, 0 for all, or a name such as 短剧)."},"version":{"type":"string","enum":["flow_split","base"],"description":"The ranking's version from kind ranking_types (flow_split default)."},"period":{"type":"integer","enum":[1,7,30],"description":"1 (daily, where ranking_types lists it), 7 (weekly) or 30 (monthly, default)."},"date":{"type":"string","pattern":"^[0-9]{8}$","maxLength":8,"description":"Ranking date, YYYYMMDD (from kind ranking_types)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["code"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/xingtu_trends":{"post":{"operationId":"social_read_xingtu_trends","summary":"Public social xingtu_trends","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_search":{"post":{"operationId":"social_read_pugongying_search","summary":"Public social pugongying_search","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"search_type":{"type":"string","enum":["NICKNAME","NOTE"],"description":"NICKNAME (default) or NOTE."},"sort":{"type":"string","enum":["DEFAULT","FANS"],"description":"DEFAULT or FANS (most followers first)."},"followers_min":{"type":"integer","minimum":0,"maximum":1000000000},"followers_max":{"type":"integer","minimum":0,"maximum":1000000000},"gender":{"type":"string","enum":["ALL","MALE","FEMALE"]},"note_type":{"type":"string","enum":["ALL","PHOTO_TEXT","VIDEO"]},"note_price":{"type":"string","pattern":"^[0-9.]*[-,][0-9.]*$","maxLength":40,"description":"Photo-note rate in RMB, min,max (-1 for open)."},"video_price":{"type":"string","pattern":"^[0-9.]*[-,][0-9.]*$","maxLength":40,"description":"Video-note rate in RMB, min,max (-1 for open)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_creator":{"post":{"operationId":"social_read_pugongying_creator","summary":"Public social pugongying_creator","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_followers":{"post":{"operationId":"social_read_pugongying_followers","summary":"Public social pugongying_followers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_follower_summary":{"post":{"operationId":"social_read_pugongying_follower_summary","summary":"Public social pugongying_follower_summary","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_follower_trend":{"post":{"operationId":"social_read_pugongying_follower_trend","summary":"Public social pugongying_follower_trend","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."},"period":{"type":"string","enum":["DAY_30","DAY_90"],"description":"DAY_30 (default) or DAY_90."},"type":{"type":"string","enum":["FANS_TOTAL","FANS_INCREASE"],"description":"FANS_TOTAL (default) or FANS_INCREASE."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_results":{"post":{"operationId":"social_read_pugongying_results","summary":"Public social pugongying_results","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."},"business":{"type":"string","enum":["DAILY_NOTE","COOPERATE_NOTE"],"description":"DAILY_NOTE (everyday notes, default) or COOPERATE_NOTE (paid ones)."},"note_type":{"type":"string","enum":["PHOTO_TEXT_AND_VIDEO","PHOTO_TEXT","VIDEO"],"description":"PHOTO_TEXT_AND_VIDEO (default), PHOTO_TEXT or VIDEO."},"period":{"type":"string","enum":["DAY_30","DAY_90"],"description":"DAY_30 (default) or DAY_90."},"ads":{"type":"string","enum":["ALL","ORGANIC_ONLY"],"description":"ALL (default) or ORGANIC_ONLY."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_note_stats":{"post":{"operationId":"social_read_pugongying_note_stats","summary":"Public social pugongying_note_stats","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."},"business":{"type":"string","enum":["DAILY_NOTE","COOPERATE_NOTE"],"description":"DAILY_NOTE (everyday notes, default) or COOPERATE_NOTE (paid ones)."},"note_type":{"type":"string","enum":["PHOTO_TEXT_AND_VIDEO","PHOTO_TEXT","VIDEO"],"description":"PHOTO_TEXT_AND_VIDEO (default), PHOTO_TEXT or VIDEO."},"period":{"type":"string","enum":["DAY_30","DAY_90"],"description":"DAY_30 (default) or DAY_90."},"ads":{"type":"string","enum":["ALL","ORGANIC_ONLY"],"description":"ALL (default) or ORGANIC_ONLY."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_notes":{"post":{"operationId":"social_read_pugongying_notes","summary":"Public social pugongying_notes","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."},"order":{"type":"string","enum":["LATEST","MOST_READ","MOST_INTERACT"],"description":"LATEST (default), MOST_READ or MOST_INTERACT."},"note_type":{"type":"string","enum":["ALL","COOPERATION","PHOTO_TEXT","VIDEO"],"description":"ALL (default), COOPERATION (paid notes), PHOTO_TEXT or VIDEO."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_similar":{"post":{"operationId":"social_read_pugongying_similar","summary":"Public social pugongying_similar","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_cost":{"post":{"operationId":"social_read_pugongying_cost","summary":"Public social pugongying_cost","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_tags":{"post":{"operationId":"social_read_pugongying_tags","summary":"Public social pugongying_tags","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Pugongying creator id (a Xiaohongshu user id)."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["user_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_note":{"post":{"operationId":"social_read_pugongying_note","summary":"Public social pugongying_note","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"note_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Xiaohongshu note id."}},"required":["note_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pugongying_trending_notes":{"post":{"operationId":"social_read_pugongying_trending_notes","summary":"Public social pugongying_trending_notes","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"type":{"type":"string","enum":["XIAOHONGSHU_HOT","PRODUCT_SEEDING","ECOMMERCE_PROMOTION","PUGONGYING_COOPERATION","LEAD_COLLECTION","ECOMMERCE_HOT","SEEDING_DIRECT","APP_PROMOTION"],"description":"XIAOHONGSHU_HOT (default), PRODUCT_SEEDING, ECOMMERCE_PROMOTION, PUGONGYING_COOPERATION …"},"order":{"type":"string","enum":["premium_imp_num","premium_good_read_rate","premium_read_num","premium_engage_num","premium_engage_rate","premium_like_num","premium_fav_num","premium_cmt_num"],"description":"Ranked by premium_imp_num (exposure, default), premium_read_num, premium_engage_num …"},"period":{"type":"string","enum":["DAY_3","DAY_7","DAY_14","DAY_30"],"description":"DAY_7 by default."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/huxuan_channels":{"post":{"operationId":"social_read_huxuan_channels","summary":"Public social huxuan_channels","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/huxuan_accounts":{"post":{"operationId":"social_read_huxuan_accounts","summary":"Public social huxuan_accounts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":256},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/huxuan_channel":{"post":{"operationId":"social_read_huxuan_channel","summary":"Public social huxuan_channel","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"app_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"QQ Huxuan creator app id (from a Huxuan search)."}},"required":["app_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/huxuan_account":{"post":{"operationId":"social_read_huxuan_account","summary":"Public social huxuan_account","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"app_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"QQ Huxuan creator app id (from a Huxuan search)."}},"required":["app_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/huxuan_channel_videos":{"post":{"operationId":"social_read_huxuan_channel_videos","summary":"Public social huxuan_channel_videos","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"app_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"QQ Huxuan creator app id (from a Huxuan search)."},"type":{"type":"string","enum":["ALL","ORDER","HOT","PERSON"],"description":"ALL (default), ORDER (paid), HOT or PERSON."},"start_date":{"type":"string","pattern":"^[0-9]{8}$","maxLength":8,"description":"First day, YYYYMMDD."},"end_date":{"type":"string","pattern":"^[0-9]{8}$","maxLength":8,"description":"Last day, YYYYMMDD."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["app_id","start_date","end_date"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/huxuan_account_articles":{"post":{"operationId":"social_read_huxuan_account_articles","summary":"Public social huxuan_account_articles","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"app_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"QQ Huxuan creator app id (from a Huxuan search)."},"query":{"type":"string","minLength":1,"maxLength":256},"type":{"type":"string","enum":["ALL","ORDER"],"description":"ALL (default) or ORDER (paid)."},"start_date":{"type":"string","pattern":"^[0-9]{8}$","maxLength":8,"description":"First day, YYYYMMDD."},"end_date":{"type":"string","pattern":"^[0-9]{8}$","maxLength":8,"description":"Last day, YYYYMMDD."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["app_id","start_date","end_date"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_accounts":{"post":{"operationId":"social_read_google_ads_accounts","summary":"Public social google_ads_accounts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_account":{"post":{"operationId":"social_read_google_ads_account","summary":"Public social google_ads_account","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."}},"required":["customer_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_campaigns":{"post":{"operationId":"social_read_google_ads_campaigns","summary":"Public social google_ads_campaigns","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."}},"required":["customer_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_adgroups":{"post":{"operationId":"social_read_google_ads_adgroups","summary":"Public social google_ads_adgroups","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."}},"required":["customer_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_ads":{"post":{"operationId":"social_read_google_ads_ads","summary":"Public social google_ads_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."}},"required":["customer_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_keywords":{"post":{"operationId":"social_read_google_ads_keywords","summary":"Public social google_ads_keywords","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."}},"required":["customer_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_search_terms":{"post":{"operationId":"social_read_google_ads_search_terms","summary":"Public social google_ads_search_terms","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."}},"required":["customer_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/google_ads_query":{"post":{"operationId":"social_read_google_ads_query","summary":"Public social google_ads_query","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_id":{"type":"string","pattern":"^[0-9]{10}$","maxLength":10,"description":"Google Ads customer id, 10 digits without dashes."},"gaql":{"type":"string","minLength":1,"maxLength":2000,"description":"A GAQL SELECT, e.g. SELECT campaign.name, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."}},"required":["customer_id","gaql"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ads_accounts":{"post":{"operationId":"social_read_meta_ads_accounts","summary":"Public social meta_ads_accounts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ads_campaigns":{"post":{"operationId":"social_read_meta_ads_campaigns","summary":"Public social meta_ads_campaigns","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^act_[0-9]{1,20}$","maxLength":24,"description":"Meta ad account id, act_… (from kind accounts)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ads_adsets":{"post":{"operationId":"social_read_meta_ads_adsets","summary":"Public social meta_ads_adsets","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^act_[0-9]{1,20}$","maxLength":24,"description":"Meta ad account id, act_… (from kind accounts)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ads_ads":{"post":{"operationId":"social_read_meta_ads_ads","summary":"Public social meta_ads_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^act_[0-9]{1,20}$","maxLength":24,"description":"Meta ad account id, act_… (from kind accounts)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/meta_ads_insights":{"post":{"operationId":"social_read_meta_ads_insights","summary":"Public social meta_ads_insights","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"object_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"act_… for the whole account, or a campaign, ad set or ad id."},"period":{"type":"string","enum":["today","yesterday","last_7d","last_14d","last_30d","this_month","maximum"],"description":"last_30d by default."},"level":{"type":"string","enum":["account","campaign","adset","ad"],"description":"Granularity of the rows."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":10}},"required":["object_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ads_campaigns":{"post":{"operationId":"social_read_tiktok_ads_campaigns","summary":"Public social tiktok_ads_campaigns","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"advertiser_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok advertiser id."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["advertiser_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ads_adgroups":{"post":{"operationId":"social_read_tiktok_ads_adgroups","summary":"Public social tiktok_ads_adgroups","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"advertiser_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok advertiser id."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["advertiser_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ads_ads":{"post":{"operationId":"social_read_tiktok_ads_ads","summary":"Public social tiktok_ads_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"advertiser_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok advertiser id."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["advertiser_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/tiktok_ads_report":{"post":{"operationId":"social_read_tiktok_ads_report","summary":"Public social tiktok_ads_report","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"advertiser_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"TikTok advertiser id."},"data_level":{"type":"string","enum":["AUCTION_ADVERTISER","AUCTION_CAMPAIGN","AUCTION_ADGROUP","AUCTION_AD"],"description":"Row level; dimensions must name its id (campaign_id for AUCTION_CAMPAIGN)."},"dimensions":{"type":"string","minLength":1,"maxLength":200,"description":"JSON array, e.g. [\"campaign_id\",\"stat_time_day\"]."},"metrics":{"type":"string","minLength":1,"maxLength":400,"description":"JSON array, e.g. [\"spend\",\"impressions\",\"clicks\",\"ctr\"]."},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"First day, YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"Last day, YYYY-MM-DD (about 30 days at most)."},"page":{"type":"integer","minimum":1,"maximum":50,"description":"Page number, from 1."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["advertiser_id","data_level","dimensions","start_date","end_date"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pinterest_ads_accounts":{"post":{"operationId":"social_read_pinterest_ads_accounts","summary":"Public social pinterest_ads_accounts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":100}},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pinterest_ads_campaigns":{"post":{"operationId":"social_read_pinterest_ads_campaigns","summary":"Public social pinterest_ads_campaigns","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Pinterest ad account id (from kind accounts)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pinterest_ads_adgroups":{"post":{"operationId":"social_read_pinterest_ads_adgroups","summary":"Public social pinterest_ads_adgroups","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Pinterest ad account id (from kind accounts)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pinterest_ads_ads":{"post":{"operationId":"social_read_pinterest_ads_ads","summary":"Public social pinterest_ads_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Pinterest ad account id (from kind accounts)."},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"next_cursor from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pinterest_ads_campaign_report":{"post":{"operationId":"social_read_pinterest_ads_campaign_report","summary":"Public social pinterest_ads_campaign_report","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Pinterest ad account id (from kind accounts)."},"campaign_ids":{"type":"string","minLength":1,"maxLength":600,"description":"Campaign ids, comma-separated."},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"First day, YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"Last day, YYYY-MM-DD."},"granularity":{"type":"string","enum":["TOTAL","DAY","WEEK","MONTH"],"description":"TOTAL by default."}},"required":["ad_account_id","campaign_ids","start_date","end_date"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/pinterest_ads_report":{"post":{"operationId":"social_read_pinterest_ads_report","summary":"Public social pinterest_ads_report","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Pinterest ad account id (from kind accounts)."},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"First day, YYYY-MM-DD (within the last 90 days)."},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10,"description":"Last day, YYYY-MM-DD."},"granularity":{"type":"string","enum":["TOTAL","DAY","WEEK","MONTH"],"description":"DAY by default."}},"required":["ad_account_id","start_date","end_date"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/snapchat_ads_organizations":{"post":{"operationId":"social_read_snapchat_ads_organizations","summary":"Public social snapchat_ads_organizations","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/snapchat_ads_accounts":{"post":{"operationId":"social_read_snapchat_ads_accounts","summary":"Public social snapchat_ads_accounts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"organization_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Snapchat organization id (a UUID)."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["organization_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/snapchat_ads_campaigns":{"post":{"operationId":"social_read_snapchat_ads_campaigns","summary":"Public social snapchat_ads_campaigns","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Snapchat ad account id (a UUID)."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/snapchat_ads_ads":{"post":{"operationId":"social_read_snapchat_ads_ads","summary":"Public social snapchat_ads_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Snapchat ad account id (a UUID)."},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/snapchat_ads_campaign_report":{"post":{"operationId":"social_read_snapchat_ads_campaign_report","summary":"Public social snapchat_ads_campaign_report","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"campaign_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Snapchat campaign id (a UUID)."},"granularity":{"type":"string","enum":["TOTAL","DAY","HOUR","LIFETIME"],"description":"LIFETIME by default."},"start_time":{"type":"string","minLength":1,"maxLength":40,"description":"ISO 8601 with offset, at midnight in the account's time zone."},"end_time":{"type":"string","minLength":1,"maxLength":40,"description":"ISO 8601 with offset (exclusive)."}},"required":["campaign_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/snapchat_ads_report":{"post":{"operationId":"social_read_snapchat_ads_report","summary":"Public social snapchat_ads_report","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ad_account_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","maxLength":128,"description":"Snapchat ad account id (a UUID)."},"granularity":{"type":"string","enum":["TOTAL","DAY","HOUR","LIFETIME"],"description":"LIFETIME by default."},"start_time":{"type":"string","minLength":1,"maxLength":40,"description":"ISO 8601 with offset, at midnight in the account's time zone."},"end_time":{"type":"string","minLength":1,"maxLength":40,"description":"ISO 8601 with offset (exclusive)."}},"required":["ad_account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/microsoft_ads_campaigns":{"post":{"operationId":"social_read_microsoft_ads_campaigns","summary":"Public social microsoft_ads_campaigns","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Microsoft Advertising account id."}},"required":["account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/microsoft_ads_adgroups":{"post":{"operationId":"social_read_microsoft_ads_adgroups","summary":"Public social microsoft_ads_adgroups","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"campaign_id":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Campaign id (from kind campaigns)."}},"required":["campaign_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/microsoft_ads_ads":{"post":{"operationId":"social_read_microsoft_ads_ads","summary":"Public social microsoft_ads_ads","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"adgroup_id":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Ad group id (from kind adgroups)."}},"required":["adgroup_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/microsoft_ads_keywords":{"post":{"operationId":"social_read_microsoft_ads_keywords","summary":"Public social microsoft_ads_keywords","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"adgroup_id":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Ad group id (from kind adgroups)."}},"required":["adgroup_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_accounts":{"post":{"operationId":"social_read_gtm_accounts","summary":"Public social gtm_accounts","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_containers":{"post":{"operationId":"social_read_gtm_containers","summary":"Public social gtm_containers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."}},"required":["account_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_workspaces":{"post":{"operationId":"social_read_gtm_workspaces","summary":"Public social gtm_workspaces","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."},"container_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager container id (digits)."}},"required":["account_id","container_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_live_version":{"post":{"operationId":"social_read_gtm_live_version","summary":"Public social gtm_live_version","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."},"container_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager container id (digits)."}},"required":["account_id","container_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_versions":{"post":{"operationId":"social_read_gtm_versions","summary":"Public social gtm_versions","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."},"container_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager container id (digits)."}},"required":["account_id","container_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_tags":{"post":{"operationId":"social_read_gtm_tags","summary":"Public social gtm_tags","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."},"container_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager container id (digits)."},"workspace_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager workspace id (digits)."}},"required":["account_id","container_id","workspace_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_triggers":{"post":{"operationId":"social_read_gtm_triggers","summary":"Public social gtm_triggers","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."},"container_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager container id (digits)."},"workspace_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager workspace id (digits)."}},"required":["account_id","container_id","workspace_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/social/gtm_variables":{"post":{"operationId":"social_read_gtm_variables","summary":"Public social gtm_variables","tags":["Public social discovery"],"description":"Public social read for the Social server's scrape side. No Sume credit charge; upstream requests consume vendor credits. Default sync waits up to 30 seconds; 202 means call again with the same Idempotency-Key. One page per call; next_cursor continues. No login, private accounts, cookies, downloads or contact data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager account id (digits)."},"container_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager container id (digits)."},"workspace_id":{"type":"string","pattern":"^[0-9]{1,32}$","maxLength":32,"description":"Tag Manager workspace id (digits)."}},"required":["account_id","container_id","workspace_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Service account is not allowed to read social data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Service account is not allowed to read social data."}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/hyperframes-previews":{"post":{"operationId":"submitHyperframesPreviewJob","summary":"Preview a HyperFrames composition as stills","tags":["Video Frames"],"description":"Captures 1-6 PNG stills of a HyperFrames composition without rendering it. Stages exactly what a bake would stage — the same clips, kit fonts and duration bind — then boots Chromium once and screenshots the requested times. No MP4 is produced and no encode runs. Omitting `at` samples 10%, 50% and 97% of the clamped duration. Reserved at the job's compute ceiling and captured at its own compute, never above the reservation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HyperframesPreviewCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"202":{"description":"Queued HyperFrames preview job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HyperframesPreviewSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/hyperframes-previews/{id}":{"get":{"operationId":"getHyperframesPreview","summary":"Get composition preview stills","tags":["Video Frames"],"description":"Returns the preview's status and, once ready, frames[{t,url,width,height}] as durable media.sume.com PNG artifacts stamped stage preview.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"HyperFrames preview resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HyperframesPreviewResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-analyses":{"post":{"operationId":"submitVideoAnalysisJob","summary":"Submit video analysis job","tags":["Video Analyses"],"description":"Starts a scene-by-scene analysis of a public HTTPS video URL. Creates a queued video_analysis job and vana_ resource, probes the video, has a video-understanding model (TwelveLabs) segment and describe it into a typed scenes[] breakdown, and extracts ≥1 ffmpeg JPEG still per second of each scene (`keyframes`) plus a representative `keyframe_url`. Analysis only — never generates video. Fixed estimate 19 credits per accepted analysis (≤120s). YouTube URLs are rejected with unsupported_source. Longer videos are less accurate — short clips give the most reliable results. Typical runtime 3–5 minutes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAnalysisCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued video analysis resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAnalysisSubmitResponse"}}}},"202":{"description":"Queued video analysis resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAnalysisSubmitResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Generic model-run submit conflicts. Possible stable `error.code` values depend on the resolved Sume model and include `avatar_handle_taken`, `avatar_not_ready`, and `idempotency_conflict`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"operationId":"listVideoAnalyses","summary":"List video analyses","tags":["Video Analyses"],"description":"Lists video-analysis resources newest-first for the authenticated workspace. Accepts limit (1–100) and status filters, including ready as an alias for completed.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["queued","processing","completed","failed","canceled","ready"]},"in":"query","name":"status","required":false,"description":"`ready` is accepted as a resource-friendly alias for completed jobs."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video analysis list scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAnalysisListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/video-analyses/{id}":{"get":{"operationId":"getVideoAnalysis","summary":"Get video analysis resource","tags":["Video Analyses"],"description":"Returns public-safe video analysis status and, when ready, the typed scenes[] breakdown with representative `keyframe_url` and dense `keyframes[{t,url}]`. Temp paths, provider ids, signed source URLs, and raw model output are omitted.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Video analysis resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAnalysisResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/actions":{"get":{"operationId":"listActions","summary":"List Actions","tags":["Actions"],"description":"Lists Actions owned by the authenticated user. Requires `actions:read`. Instructions text is omitted from the public Action shape.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["active","inactive"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["cron","api"]},"in":"query","name":"trigger_type","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Actions owned by the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/actions/{action_id}":{"get":{"operationId":"getAction","summary":"Get Action","tags":["Actions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"action_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action owned by the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/actions/{action_id}/runs":{"get":{"operationId":"listActionRuns","summary":"List Action runs","tags":["Actions"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"action_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action runs, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createActionRun","summary":"Create Action run (API-call trigger)","tags":["Actions"],"description":"Starts an Action run via the API-call trigger and returns a `PublicActionRun` receipt. Requires `actions:write`. The call is always asynchronous: poll `status_url` / `GET /v1/action-runs/{id}`, or supply `communication.webhook_url` to be sent one signed `action.run.terminal` POST (see `RunWebhookEvent`) when the run finishes. Webhook delivery is live on both `api.dev.sume.com` and `api.sume.com`. A canceled run never delivers a webhook. Media fields in a completed receipt are durable `media.sume.com` HTTPS URLs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"input":{"type":"object","additionalProperties":true},"on_active_run":{"type":"string","enum":["skip","reject"],"default":"skip"},"generation_spend_cap_credits":{"type":["integer","null"],"minimum":0,"description":"Most this run may spend on generation, in credits. Omit to inherit the Format/Action cap. `null` runs with no automation ceiling — wallet balance, generation admission and org limits still apply. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"action_id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"202":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Action run refused on authorization. Stable `error.code` value: `insufficient_scope` when the key lacks `actions:write` or is a service-account key.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Action run submit conflicts. Stable `error.code` values: `action_run_in_progress` when `on_active_run: \"reject\"` was sent and the Action already has a run in flight, `action_inactive` / `action_api_trigger_disabled` when the API-call trigger is not provisioned or is switched off, and `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/actions/{handle}/{slug}/runs":{"post":{"operationId":"createActionRunByVanityPath","summary":"Create Action run by handle and slug","tags":["Actions"],"description":"Same as `POST /v1/actions/{action_id}/runs`, addressed by the owner's handle and the Action's slug. Requires `actions:write`. The receipt's `action.id` is always the opaque `aut_…` id, which is the durable identifier — store that, not the vanity path, since a handle or slug rename changes the URL. Renamed handles keep resolving for 90 days.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"input":{"type":"object","additionalProperties":true},"on_active_run":{"type":"string","enum":["skip","reject"],"default":"skip"},"generation_spend_cap_credits":{"type":["integer","null"],"minimum":0,"description":"Most this run may spend on generation, in credits. Omit to inherit the Format/Action cap. `null` runs with no automation ceiling — wallet balance, generation admission and org limits still apply. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}}}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":2,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"202":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Action run refused on authorization. Stable `error.code` value: `insufficient_scope` when the key lacks `actions:write` or is a service-account key.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Action run submit conflicts. Stable `error.code` values: `action_run_in_progress` when `on_active_run: \"reject\"` was sent and the Action already has a run in flight, `action_inactive` / `action_api_trigger_disabled` when the API-call trigger is not provisioned or is switched off, and `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"operationId":"listActionRunsByVanityPath","summary":"List Action runs by handle and slug","tags":["Actions"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":2,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action runs, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/actions/{handle}/{slug}":{"get":{"operationId":"getActionByVanityPath","summary":"Get Action by handle and slug","tags":["Actions"],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":2,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action owned by the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/action-runs/{run_id}":{"get":{"operationId":"getActionRun","summary":"Get Action run","tags":["Actions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/action-runs/{run_id}/status":{"get":{"operationId":"getActionRunStatus","summary":"Get Action run status","tags":["Actions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Trimmed Action run status payload for polling loops.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunStatusResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/action-runs/{run_id}/result":{"get":{"operationId":"getActionRunResult","summary":"Get Action run result","tags":["Actions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The run has not reached a terminal state, so there is no result to return. `error.code` is `run_not_completed` and `details.status` carries the current status. Poll `status_url` and retry once the run is `completed`, `failed`, `canceled`, or `skipped` — every terminal state returns 200 here, including failures, because the receipt is the answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/action-runs/{run_id}/cancel":{"post":{"operationId":"cancelActionRun","summary":"Cancel Action run","tags":["Actions"],"description":"Idempotent cancel. Already-terminal runs return the terminal receipt with HTTP 200.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/actions/{action_id}/runs/{run_id}":{"get":{"operationId":"getActionRunByAction","summary":"Get Action run (aliased under Action)","tags":["Actions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"action_id","required":true},{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Action run receipt with schema-constrained output and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/skills":{"get":{"operationId":"listSkills","summary":"List first-party skills","tags":["Skills"],"description":"Lists the first-party Sume skills this environment serves: each is a package of `SKILL.md` and optional `references/` that an agent reads and follows. `atomic` skills are workflows and capability playbooks; `format` skills are the runnable presets, also listed under `/v1/formats` as `sume/{slug}`. Read a skill with `GET /v1/skills/{slug}/contents`. Reading costs nothing.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"First-party skills this environment serves.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/skills/{slug}/contents":{"get":{"operationId":"listSkillContents","summary":"List a skill's files","tags":["Skills"],"description":"Lists the files and directories at the root of a first-party skill package, in the shape GitHub's Contents API uses. `?recursive=1` returns every file with its base64 content.","parameters":[{"schema":{"type":"string","enum":["1","true"]},"in":"query","name":"recursive","required":false,"description":"Return every file of the skill, each with its base64 content, instead of the root listing."},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Format package file, or the entries under a directory or the package root.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Nothing was found at this address. Stable `error.code` values: `skill_not_found` when no first-party skill has this slug in this environment, and `skill_content_not_found` when the skill exists but has no file or directory at the path.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/formats":{"get":{"operationId":"listFormats","summary":"List Formats","tags":["Formats"],"description":"Lists Formats visible to the authenticated user (own custom Formats plus the first-party catalog). Requires `formats:read`. The `SKILL.md` body is omitted from the public Format shape.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque bookmark from a prior page's `next_cursor`. Omit for the first page."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Formats visible to the authenticated user.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"post":{"operationId":"createFormat","summary":"Create Format","tags":["Formats"],"description":"Creates an empty Format in the calling key's workspace and opens its package repository, the way `POST /repos` opens one on GitHub. Requires `formats:write`. `slug` is the name, unique within the workspace; `auto_init` (default `true`) commits a minimal valid `SKILL.md` so the Format is immediately readable and writable through the Contents API — `PUT /v1/formats/{handle}/{slug}/contents/SKILL.md` is the intended next call, and the 201 carries the `contents_url` and `package_sha` it needs. The package itself is not sent here: a Format's files have one set of rules and one endpoint, whoever writes them. The workspace comes from the key, not from the request, so there is no way to create a Format in someone else's — a team Format needs a key created in that workspace. A slug this workspace already uses is a `409`, never an overwrite. Package history is opened **before** the catalog row, so if it cannot be opened the call fails with `503 format_git_unavailable` and no Format is created, rather than one whose commits nobody can resolve.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatCreateRequest"}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"201":{"description":"The Format that was created, with the `package_sha` and `contents_url` its first Contents write needs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_authoring_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot edit Format packages.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_authoring_unsupported"}}}}}}}},"409":{"description":"The slug is already spoken for. Stable `error.code` values: `skill_slug_taken` when this workspace already has a Format with that slug, and `skill_slug_reserved` when a Format by Sume holds the name globally. Pick another slug — this call never overwrites an existing Format.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"No Format was created, rather than one whose package history does not exist. Stable `error.code` values: `format_git_unavailable` when Format package history is unreachable or not configured for this environment, and `studio_agent_upstream_unavailable` when the control plane itself could not be reached. Nothing was created; retry.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{format_id}":{"get":{"operationId":"getFormat","summary":"Get Format","tags":["Formats"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"format_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format owned by the authenticated user.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{format_id}/runs":{"post":{"operationId":"createFormatRun","summary":"Create Format run (API-call trigger)","tags":["Formats"],"description":"Starts a Format run and returns a `PublicFormatRun` receipt. Requires `formats:write`. The server composes the run instruction as a pointer at the Format's attached package followed by `instruction`; omit `instruction` to use the Format default. `SKILL.md` is written into the run's workspace for the agent to read rather than copied into the turn, so the Format body has no size limit of its own. The body must still name at least one of `instruction`, `input`, `previous_run_id`, or `attachments` — an empty body is a `400 invalid_request` rather than a billable turn on the Format default. `input` stays caller data, never instructions. Attach up to 30 images with `attachments[]` (`type: \"input_image\"` plus either a public HTTPS `image_url` or an `asset_id` from the Assets API); each is fetched and copied into Sume storage at create time, so an unreachable or oversized image fails this call instead of the run. Attachments compose with `output_schema`. The call is always asynchronous: it returns a non-terminal receipt and you learn the outcome by polling `status_url` / `GET /v1/format-runs/{run_id}`, or by supplying `communication.webhook_url` to be sent one signed `format.run.terminal` POST (see `RunWebhookEvent`) when the run finishes. Webhook delivery is live on both `api.dev.sume.com` and `api.sume.com`. A canceled run never delivers a webhook. Pass `previous_run_id` to continue a **completed** run of the same Format as a second agent turn instead of starting a fresh one: the new run joins the earlier run's thread, so the agent sees what it already produced and can revise part of it while leaving the rest alone. A continuation is a **new run** with its own id, its own spend cap, and its own single terminal webhook — poll the new id, not the old one. `400 previous_run_format_mismatch` / `previous_run_not_resumable`, `404 previous_run_not_found`, and `409 previous_run_not_terminal` say why a continuity id was refused. A canceled or failed predecessor is refused with `400 previous_run_not_resumable`: it left no receipt for the next turn to revise, so continuing it only paid for the discovery.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"instruction":{"type":"string","maxLength":8000},"input":{"type":"object","additionalProperties":true,"description":"Caller data for this run, fenced into the prompt as data and never as instructions. At most 64 top-level properties and 2097152 UTF-8 bytes, measured on the compact serialization; over either cap is a `400 invalid_request`.","maxProperties":64},"attachments":{"type":"array","maxItems":30,"items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["input_image"]},"image_url":{"type":"string","format":"uri","maxLength":2048},"asset_id":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","maxLength":180}}}},"previous_run_id":{"type":"string","minLength":1,"maxLength":128},"on_active_run":{"type":"string","enum":["allow","skip","reject"]},"generation_spend_cap_credits":{"type":["integer","null"],"minimum":0,"description":"Most this run may spend on generation, in credits, up to a platform maximum of 31,250. Omit to inherit the Format's cap (25,000 for a Format that never named one). A number above the Format's own cap is honored, not clamped; above the platform maximum is rejected. `null` runs at the platform maximum — it lifts the ceiling, it does not remove it. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"model":{"type":"string","minLength":1,"maxLength":128,"description":"Agents catalog pin for the orchestrator LLM, e.g. `gpt-6.1-sol`. Omit or send an empty string for GPT-6.1 Sol; `gpt-6-sol` and retired `gpt-5.6-sol` run GPT-6 Sol. Explicit `auto` opts into Gemini 3.8 Flash then one Sol hop on a classified transient failure, where the Auto catalog is enabled (dest first). Concrete pins do not authorize model fallback. Unknown or unavailable selections return `400 invalid_request`. Image/video/audio model selection is separate. Receipt `model` and `requested_model` echo the normalized selection; `served_model`, `fallback_used` and `model_attempts` report observed execution."},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}},"anyOf":[{"required":["instruction"]},{"required":["input"]},{"required":["previous_run_id"]},{"required":["attachments"]}]}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"format_id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format run receipt with schema-constrained output and durable media URLs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunResponse"}}}},"202":{"description":"Format run receipt with schema-constrained output and durable media URLs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"402":{"description":"The workspace cannot fund this run. Stable `error.code` values: `insufficient_credits` when the workspace's wallet holds too little (a personal workspace, or an organization workspace with a wallet), and `organization_wallet_not_provisioned` for an organization workspace that has no wallet yet. `next_action` is `add_funds` and `retryable` is `false` — retrying without topping up returns the same answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_credits":{"value":{"error":{"code":"insufficient_agent_credits","message":"Not enough credits to start this run.","request_id":"req_0123456789abcdef0123456789abcdef","category":"quota","stage":"usage_reservation","retryable":false,"public_reason":"insufficient_balance","next_action":"add_funds","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_runs_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot create Format runs in MVP.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_runs_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"previous_run_not_found":{"value":{"error":{"code":"previous_run_not_found","message":"previous_run_id does not name a run you can continue.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"Format run submit conflicts. Stable `error.code` values: `format_run_in_progress` when `on_active_run: \"reject\"` was sent and this Format already has a run in flight (the default `allow` never conflicts), `format_not_forkable` when the id names a built-in capability rather than a Format card — the curated Formats by Sume at `sume/{slug}` are directly invokable and never return this, `format_inactive` / `format_api_trigger_disabled` when the API-call trigger is not provisioned or is switched off, `previous_run_not_terminal` when `previous_run_id` names a run that has not finished yet — poll it and call again, and `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"502":{"description":"A resource Sume had to fetch for this run could not be retrieved. Stable `error.code` value: `attachment_fetch_failed` when an `attachments[].image_url` was unreachable, refused, or served something Sume could not store.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"attachment_fetch_failed":{"value":{"error":{"code":"attachment_fetch_failed","message":"attachments[0]: Unable to resolve source host: example.invalid.","request_id":"req_0123456789abcdef0123456789abcdef","category":"media","stage":"media","retryable":false,"public_reason":"attachment_fetch_failed","next_action":"fix_input","retry_after_seconds":null,"details":{"index":0}}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"get":{"operationId":"listFormatRuns","summary":"List Format runs","tags":["Formats"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"format_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format runs, newest first.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{handle}/{slug}/runs":{"post":{"operationId":"createFormatRunByVanityPath","summary":"Create Format run by handle and slug","tags":["Formats"],"description":"Same as `POST /v1/formats/{format_id}/runs`, addressed by the owner's handle and the Format's slug. Requires `formats:write`. The receipt's `format.id` is always the opaque `skl_…` id, which is the durable identifier — store that, not the vanity path, since a handle or slug rename changes the URL. Renamed handles keep resolving for 90 days. The curated Formats by Sume answer at the reserved `sume` handle (`sume/{slug}`) rather than at any account handle, and any valid key may call them — the run and its spend belong to that key. A Format owned by a team workspace needs a key created in that workspace; a personal key returns `403 workspace_key_required`. `previous_run_id` continues a completed run of this same Format as a second agent turn; the continued run must have been created on this Format, whichever URL shape addressed it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"instruction":{"type":"string","maxLength":8000},"input":{"type":"object","additionalProperties":true,"description":"Caller data for this run, fenced into the prompt as data and never as instructions. At most 64 top-level properties and 2097152 UTF-8 bytes, measured on the compact serialization; over either cap is a `400 invalid_request`.","maxProperties":64},"attachments":{"type":"array","maxItems":30,"items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["input_image"]},"image_url":{"type":"string","format":"uri","maxLength":2048},"asset_id":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","maxLength":180}}}},"previous_run_id":{"type":"string","minLength":1,"maxLength":128},"on_active_run":{"type":"string","enum":["allow","skip","reject"]},"generation_spend_cap_credits":{"type":["integer","null"],"minimum":0,"description":"Most this run may spend on generation, in credits, up to a platform maximum of 31,250. Omit to inherit the Format's cap (25,000 for a Format that never named one). A number above the Format's own cap is honored, not clamped; above the platform maximum is rejected. `null` runs at the platform maximum — it lifts the ceiling, it does not remove it. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"model":{"type":"string","minLength":1,"maxLength":128,"description":"Agents catalog pin for the orchestrator LLM, e.g. `gpt-6.1-sol`. Omit or send an empty string for GPT-6.1 Sol; `gpt-6-sol` and retired `gpt-5.6-sol` run GPT-6 Sol. Explicit `auto` opts into Gemini 3.8 Flash then one Sol hop on a classified transient failure, where the Auto catalog is enabled (dest first). Concrete pins do not authorize model fallback. Unknown or unavailable selections return `400 invalid_request`. Image/video/audio model selection is separate. Receipt `model` and `requested_model` echo the normalized selection; `served_model`, `fallback_used` and `model_attempts` report observed execution."},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}},"anyOf":[{"required":["instruction"]},{"required":["input"]},{"required":["previous_run_id"]},{"required":["attachments"]}]}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format run receipt with schema-constrained output and durable media URLs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunResponse"}}}},"202":{"description":"Format run receipt with schema-constrained output and durable media URLs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"402":{"description":"The workspace cannot fund this run. Stable `error.code` values: `insufficient_credits` when the workspace's wallet holds too little (a personal workspace, or an organization workspace with a wallet), and `organization_wallet_not_provisioned` for an organization workspace that has no wallet yet. `next_action` is `add_funds` and `retryable` is `false` — retrying without topping up returns the same answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_credits":{"value":{"error":{"code":"insufficient_agent_credits","message":"Not enough credits to start this run.","request_id":"req_0123456789abcdef0123456789abcdef","category":"quota","stage":"usage_reservation","retryable":false,"public_reason":"insufficient_balance","next_action":"add_funds","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_runs_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot create Format runs in MVP.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_runs_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"previous_run_not_found":{"value":{"error":{"code":"previous_run_not_found","message":"previous_run_id does not name a run you can continue.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"Format run submit conflicts. Stable `error.code` values: `format_run_in_progress` when `on_active_run: \"reject\"` was sent and this Format already has a run in flight (the default `allow` never conflicts), `format_not_forkable` when the id names a built-in capability rather than a Format card — the curated Formats by Sume at `sume/{slug}` are directly invokable and never return this, `format_inactive` / `format_api_trigger_disabled` when the API-call trigger is not provisioned or is switched off, `previous_run_not_terminal` when `previous_run_id` names a run that has not finished yet — poll it and call again, and `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"502":{"description":"A resource Sume had to fetch for this run could not be retrieved. Stable `error.code` value: `attachment_fetch_failed` when an `attachments[].image_url` was unreachable, refused, or served something Sume could not store.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"attachment_fetch_failed":{"value":{"error":{"code":"attachment_fetch_failed","message":"attachments[0]: Unable to resolve source host: example.invalid.","request_id":"req_0123456789abcdef0123456789abcdef","category":"media","stage":"media","retryable":false,"public_reason":"attachment_fetch_failed","next_action":"fix_input","retry_after_seconds":null,"details":{"index":0}}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"get":{"operationId":"listFormatRunsByVanityPath","summary":"List Format runs by handle and slug","tags":["Formats"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format runs, newest first.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{format_id}/bulk-runs":{"post":{"operationId":"createFormatRunQueue","summary":"Create a bulk Format-run queue","tags":["Formats"],"description":"Accepts up to 100 Format-run items and a `concurrency` window (for example 3) and returns a queue receipt. Requires `formats:write` and works with an API key. The server keeps that many child runs in flight at once; when any in-flight run hits `completed` or `failed`, the next queued item starts immediately until the list is drained. Child runs are ordinary Format runs — poll each `run_id` at `GET /v1/format-runs/{run_id}`, or poll the queue at `status_url` / `GET /v1/format-run-queues/{queue_id}` for counts. This is not client-driven fan-out.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["concurrency","items"],"properties":{"concurrency":{"type":"integer","minimum":1,"maximum":16,"description":"How many child Format runs to keep in flight at once. When any in-flight run hits completed or failed, the next queued item starts immediately so this window stays full until the list is drained."},"items":{"type":"array","minItems":1,"maxItems":100,"description":"Format-run requests to execute, in order. Each entry is the same body as `POST /v1/formats/{format_id}/runs`. Items stay queued until a concurrency slot opens.","items":{"type":"object","additionalProperties":false,"properties":{"instruction":{"type":"string","maxLength":8000},"input":{"type":"object","additionalProperties":true,"description":"Caller data for this run, fenced into the prompt as data and never as instructions. At most 64 top-level properties and 2097152 UTF-8 bytes, measured on the compact serialization; over either cap is a `400 invalid_request`."},"attachments":{"type":"array","maxItems":30,"items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["input_image"]},"image_url":{"type":"string","format":"uri","maxLength":2048},"asset_id":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","maxLength":180}}}},"previous_run_id":{"type":"string","minLength":1,"maxLength":128},"on_active_run":{"type":"string","enum":["allow","skip","reject"]},"generation_spend_cap_credits":{"type":["integer","null"],"minimum":0,"description":"Most this run may spend on generation, in credits, up to a platform maximum of 31,250. Omit to inherit the Format's cap (25,000 for a Format that never named one). A number above the Format's own cap is honored, not clamped; above the platform maximum is rejected. `null` runs at the platform maximum — it lifts the ceiling, it does not remove it. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"model":{"type":"string","minLength":1,"maxLength":128,"description":"Agents catalog pin for the orchestrator LLM, e.g. `gpt-6.1-sol`. Omit or send an empty string for GPT-6.1 Sol; `gpt-6-sol` and retired `gpt-5.6-sol` run GPT-6 Sol. Explicit `auto` opts into Gemini 3.8 Flash then one Sol hop on a classified transient failure, where the Auto catalog is enabled (dest first). Concrete pins do not authorize model fallback. Unknown or unavailable selections return `400 invalid_request`. Image/video/audio model selection is separate. Receipt `model` and `requested_model` echo the normalized selection; `served_model`, `fallback_used` and `model_attempts` report observed execution."},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":255}}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"format_id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"202":{"description":"Format bulk-run queue with concurrency, progress counts, and child run ids.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunQueueResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"402":{"description":"The workspace cannot fund this run. Stable `error.code` values: `insufficient_credits` when the workspace's wallet holds too little (a personal workspace, or an organization workspace with a wallet), and `organization_wallet_not_provisioned` for an organization workspace that has no wallet yet. `next_action` is `add_funds` and `retryable` is `false` — retrying without topping up returns the same answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_credits":{"value":{"error":{"code":"insufficient_agent_credits","message":"Not enough credits to start this run.","request_id":"req_0123456789abcdef0123456789abcdef","category":"quota","stage":"usage_reservation","retryable":false,"public_reason":"insufficient_balance","next_action":"add_funds","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_runs_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot create Format runs in MVP.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_runs_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"Format run submit conflicts. Stable `error.code` values: `format_run_in_progress` when `on_active_run: \"reject\"` was sent and this Format already has a run in flight (the default `allow` never conflicts), `format_not_forkable` when the id names a built-in capability rather than a Format card — the curated Formats by Sume at `sume/{slug}` are directly invokable and never return this, `format_inactive` / `format_api_trigger_disabled` when the API-call trigger is not provisioned or is switched off, `previous_run_not_terminal` when `previous_run_id` names a run that has not finished yet — poll it and call again, and `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"502":{"description":"A resource Sume had to fetch for this run could not be retrieved. Stable `error.code` value: `attachment_fetch_failed` when an `attachments[].image_url` was unreachable, refused, or served something Sume could not store.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"attachment_fetch_failed":{"value":{"error":{"code":"attachment_fetch_failed","message":"attachments[0]: Unable to resolve source host: example.invalid.","request_id":"req_0123456789abcdef0123456789abcdef","category":"media","stage":"media","retryable":false,"public_reason":"attachment_fetch_failed","next_action":"fix_input","retry_after_seconds":null,"details":{"index":0}}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{handle}/{slug}/bulk-runs":{"post":{"operationId":"createFormatRunQueueByVanityPath","summary":"Create a bulk Format-run queue by handle and slug","tags":["Formats"],"description":"Same as `POST /v1/formats/{format_id}/bulk-runs`, addressed by the owner's handle and the Format's slug. Requires `formats:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["concurrency","items"],"properties":{"concurrency":{"type":"integer","minimum":1,"maximum":16,"description":"How many child Format runs to keep in flight at once. When any in-flight run hits completed or failed, the next queued item starts immediately so this window stays full until the list is drained."},"items":{"type":"array","minItems":1,"maxItems":100,"description":"Format-run requests to execute, in order. Each entry is the same body as `POST /v1/formats/{format_id}/runs`. Items stay queued until a concurrency slot opens.","items":{"type":"object","additionalProperties":false,"properties":{"instruction":{"type":"string","maxLength":8000},"input":{"type":"object","additionalProperties":true,"description":"Caller data for this run, fenced into the prompt as data and never as instructions. At most 64 top-level properties and 2097152 UTF-8 bytes, measured on the compact serialization; over either cap is a `400 invalid_request`."},"attachments":{"type":"array","maxItems":30,"items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["input_image"]},"image_url":{"type":"string","format":"uri","maxLength":2048},"asset_id":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","maxLength":180}}}},"previous_run_id":{"type":"string","minLength":1,"maxLength":128},"on_active_run":{"type":"string","enum":["allow","skip","reject"]},"generation_spend_cap_credits":{"type":["integer","null"],"minimum":0,"description":"Most this run may spend on generation, in credits, up to a platform maximum of 31,250. Omit to inherit the Format's cap (25,000 for a Format that never named one). A number above the Format's own cap is honored, not clamped; above the platform maximum is rejected. `null` runs at the platform maximum — it lifts the ceiling, it does not remove it. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"model":{"type":"string","minLength":1,"maxLength":128,"description":"Agents catalog pin for the orchestrator LLM, e.g. `gpt-6.1-sol`. Omit or send an empty string for GPT-6.1 Sol; `gpt-6-sol` and retired `gpt-5.6-sol` run GPT-6 Sol. Explicit `auto` opts into Gemini 3.8 Flash then one Sol hop on a classified transient failure, where the Auto catalog is enabled (dest first). Concrete pins do not authorize model fallback. Unknown or unavailable selections return `400 invalid_request`. Image/video/audio model selection is separate. Receipt `model` and `requested_model` echo the normalized selection; `served_model`, `fallback_used` and `model_attempts` report observed execution."},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":255}}}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"202":{"description":"Format bulk-run queue with concurrency, progress counts, and child run ids.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunQueueResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"402":{"description":"The workspace cannot fund this run. Stable `error.code` values: `insufficient_credits` when the workspace's wallet holds too little (a personal workspace, or an organization workspace with a wallet), and `organization_wallet_not_provisioned` for an organization workspace that has no wallet yet. `next_action` is `add_funds` and `retryable` is `false` — retrying without topping up returns the same answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_credits":{"value":{"error":{"code":"insufficient_agent_credits","message":"Not enough credits to start this run.","request_id":"req_0123456789abcdef0123456789abcdef","category":"quota","stage":"usage_reservation","retryable":false,"public_reason":"insufficient_balance","next_action":"add_funds","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_runs_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot create Format runs in MVP.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_runs_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"Format run submit conflicts. Stable `error.code` values: `format_run_in_progress` when `on_active_run: \"reject\"` was sent and this Format already has a run in flight (the default `allow` never conflicts), `format_not_forkable` when the id names a built-in capability rather than a Format card — the curated Formats by Sume at `sume/{slug}` are directly invokable and never return this, `format_inactive` / `format_api_trigger_disabled` when the API-call trigger is not provisioned or is switched off, `previous_run_not_terminal` when `previous_run_id` names a run that has not finished yet — poll it and call again, and `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"502":{"description":"A resource Sume had to fetch for this run could not be retrieved. Stable `error.code` value: `attachment_fetch_failed` when an `attachments[].image_url` was unreachable, refused, or served something Sume could not store.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"attachment_fetch_failed":{"value":{"error":{"code":"attachment_fetch_failed","message":"attachments[0]: Unable to resolve source host: example.invalid.","request_id":"req_0123456789abcdef0123456789abcdef","category":"media","stage":"media","retryable":false,"public_reason":"attachment_fetch_failed","next_action":"fix_input","retry_after_seconds":null,"details":{"index":0}}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{handle}/{slug}":{"get":{"operationId":"getFormatByVanityPath","summary":"Get Format by handle and slug","tags":["Formats"],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format owned by the authenticated user.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{handle}/{slug}/grants":{"get":{"operationId":"listFormatGrants","summary":"List Format workspace grants","tags":["Formats"],"description":"Lists the live (pending and accepted) workspace grants on a Format, newest first. Requires `formats:read` and a key created in the Format's own team workspace — grants are managed by the owner workspace only. Revoked grants do not list.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Live (pending and accepted) workspace grants, newest first.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"post":{"operationId":"createFormatGrant","summary":"Invite a workspace to run a Format","tags":["Formats"],"description":"Invites another team workspace to run this Format. The grant starts `pending` and confers nothing until an admin of the invited workspace accepts it — then that workspace lists, reads and invokes the Format at this same `{handle}/{slug}` address, with runs billed to the invited (grantee) workspace. The only role is `run`: package Contents stay writable by the owner workspace alone, and no bytes are copied — a revoke is complete by construction. Requires `formats:write` and a key created in the Format's own team workspace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantCreateRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"201":{"description":"One workspace grant on a Format.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"workspace_not_found":{"value":{"error":{"code":"workspace_not_found","message":"No team workspace answers to that handle.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"The pair is already related. Stable `error.code` values: `format_grant_exists` when that workspace already holds a pending or accepted grant (revoke it first to re-invite), `format_grant_self` when the workspace already owns the Format, and `format_workspace_required` when the Format is not owned by a team workspace at all — only team Formats can be shared.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{handle}/{slug}/grants/{workspace}":{"delete":{"operationId":"revokeFormatGrant","summary":"Revoke a Format workspace grant","tags":["Formats"],"description":"Revokes a workspace's grant on this Format — pending or accepted. The grantee's in-flight runs finish; new lists, reads and invokes fail closed immediately. `{workspace}` takes the grantee's team handle or its `org_…` id. Requires `formats:write` and a key created in the Format's own team workspace.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":2,"maxLength":64},"in":"path","name":"workspace","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One workspace grant on a Format.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_grant_not_found":{"value":{"error":{"code":"format_grant_not_found","message":"Format grant not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"patch":{"operationId":"updateFormatGrant","summary":"Change a Format workspace grant's role","tags":["Formats"],"description":"Changes what a workspace's grant on this Format allows — `run` (list, read, invoke, overlay) or `write` (that, plus editing the package through the Contents API at this same address). Applies to pending grants too, so the grantee accepts the role actually on offer. Raising to `write` takes effect on the grantee's next authoring call; lowering to `run` closes the package immediately. `{workspace}` takes the grantee's team handle or its `org_…` id. Requires `formats:write` and a key created in the Format's own team workspace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantUpdateRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":2,"maxLength":64},"in":"path","name":"workspace","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One workspace grant on a Format.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_grant_not_found":{"value":{"error":{"code":"format_grant_not_found","message":"Format grant not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-grants":{"get":{"operationId":"listWorkspaceFormatGrants","summary":"List Formats shared with your workspace","tags":["Formats"],"description":"Lists the live grants shared *with* the calling key's team workspace, newest first — pending invites an admin can accept, plus the accepted ones. A personal key holds no workspace grants and reads an empty list. Requires `formats:read`.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Live (pending and accepted) workspace grants, newest first.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-grants/{grant_id}/accept":{"post":{"operationId":"acceptFormatGrant","summary":"Accept a Format grant","tags":["Formats"],"description":"Accepts a pending grant as the calling key's team workspace. From then on the workspace lists, reads and invokes the Format at the owner's `{handle}/{slug}`, billed to itself. Idempotent — accepting an already-accepted grant answers it unchanged. A grant invited to a different workspace is a `404`, indistinguishable from an unknown id. Requires `formats:write` and a team-workspace key; a personal key returns `403 workspace_key_required`.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"grant_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One workspace grant on a Format.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatGrantResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_grant_not_found":{"value":{"error":{"code":"format_grant_not_found","message":"Format grant not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/formats/{handle}/{slug}/contents":{"get":{"operationId":"listFormatContents","summary":"List Format package contents","tags":["Formats"],"description":"Lists the files and directories at the root of a Format's package, in the shape GitHub's Contents API uses. Requires `formats:read`. Each `file` entry carries the git blob `sha` that `PUT`/`DELETE` take as their precondition, so this is the read half of a read-modify-write. File bodies are not included here — fetch one path with `GET /v1/formats/{handle}/{slug}/contents/{path}`, or pass `?recursive=1` to get the whole package, bodies included, in one call.","parameters":[{"schema":{"type":"string","enum":["0","1","false","true"]},"in":"query","name":"recursive","required":false,"description":"Set to `1` (or `true`) to return every file in the package, each with its base64 body, instead of the root listing."},{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Format package file, or the entries under a directory or the package root.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"Nothing was found at this address for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, or outside the calling key's workspace, and `format_content_not_found` when the Format exists but holds no file or directory at that path. Both are deliberately indistinguishable from a permission failure. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_content_not_found":{"value":{"error":{"code":"format_content_not_found","message":"No file or directory at \"references/plan.md\" in this Format package.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"put":{"operationId":"putFormatContents","summary":"Commit several Format package files at once","tags":["Formats"],"description":"Writes every file in `files` into a Format's package as **one** commit, one `version` bump, and one new `package_sha`. Requires `formats:write`. This is the multi-file sibling of `PUT /v1/formats/{handle}/{slug}/contents/{path}`, and each entry follows that endpoint's rules: `content` is the whole new file base64-encoded, and `sha` is required when the path already exists and omitted to create it. `files` is a change set, not the package — **paths the package holds but this body omits are kept unchanged**, so editing two files never risks the other ten. Deletions are not expressible here; remove a file with `DELETE …/contents/{path}`. Send `If-Match: <package_sha>` to refuse the commit if the package moved since you read it. The resulting package is validated as a whole before anything is committed, and a package that breaks a rule is never committed — as with the single-file write, a history outage fails with `503 format_git_unavailable` rather than saving a Format whose commit sha nobody can resolve.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentBatchPutRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","pattern":"^[0-9a-f]{40}$"},"in":"header","name":"if-match","required":false,"description":"Package precondition: the Format's `package_sha` (the `commit.tree.sha` of the write you last read). The write is refused with `409 format_package_sha_mismatch` if the package has moved since. Ignored on Formats published before `package_sha` existed, which carry none. Omit it to rely on per-file `sha` alone."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"The files this commit wrote and the commit it produced.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentBatchWriteResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_authoring_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot edit Format packages.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_authoring_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"Nothing was found at this address for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, or outside the calling key's workspace, and `format_content_not_found` when the Format exists but holds no file or directory at that path. Both are deliberately indistinguishable from a permission failure. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_content_not_found":{"value":{"error":{"code":"format_content_not_found","message":"No file or directory at \"references/plan.md\" in this Format package.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"The write was refused because the caller's view of the package is stale. Stable `error.code` values: `format_content_sha_required` when the path already exists and no `sha` was sent, `format_content_sha_mismatch` when the `sha` does not match the stored file (or names a path that does not exist), `format_package_sha_mismatch` when the `If-Match` package sha is not the Format's current one, `format_authoring_in_progress` while an AI-authored Format is still being written, and `skill_slug_taken` / `skill_slug_reserved` from package validation. Re-read `GET …/contents/{path}` and retry with the returned `sha`; `format_package_sha_mismatch` carries the current package sha in `error.details.package_sha`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The write was refused rather than saved without a commit. Stable `error.code` values: `format_git_unavailable` when Format package history is unreachable or not configured for this environment, and `studio_agent_upstream_unavailable` when the control plane itself could not be reached. Nothing was changed; retry.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-run-queues/{queue_id}":{"get":{"operationId":"getFormatRunQueue","summary":"Get Format bulk-run queue","tags":["Formats"],"description":"Progress for a bulk Format-run queue. Requires `formats:read`. `counts` are queued / running / completed / failed / canceled. Child receipts stay at `GET /v1/format-runs/{run_id}`.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"queue_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format bulk-run queue with concurrency, progress counts, and child run ids.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunQueueResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_queue_not_found":{"value":{"error":{"code":"format_run_queue_not_found","message":"Format run queue not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-runs/{run_id}":{"get":{"operationId":"getFormatRun","summary":"Get Format run","tags":["Formats"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format run receipt with schema-constrained output and durable media URLs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_not_found":{"value":{"error":{"code":"format_run_not_found","message":"Format run not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-runs/{run_id}/status":{"get":{"operationId":"getFormatRunStatus","summary":"Get Format run status","tags":["Formats"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Trimmed Format run status payload for polling loops.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunStatusResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_not_found":{"value":{"error":{"code":"format_run_not_found","message":"Format run not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-runs/{run_id}/events":{"get":{"operationId":"listFormatRunEvents","summary":"List Format run phase events","tags":["Formats"],"description":"Phase timeline for a run, oldest first. Answers 'what is it doing and since when' while a run is in flight — the question `status` alone cannot. Entries are phases (`preparing`, `running`, `finalizing`) with a status and, where the phase measured one, a duration. This is deliberately not a log stream: agent output, tool calls, sandbox identifiers and free-text stage messages are internal and are never published here. An empty array is a normal answer for a run that has not started yet, or for a `skipped` run that never got one.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Phase timeline for a Format run.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunEventsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_not_found":{"value":{"error":{"code":"format_run_not_found","message":"Format run not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-runs/{run_id}/result":{"get":{"operationId":"getFormatRunResult","summary":"Get Format run result","tags":["Formats"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format run receipt with schema-constrained output and durable media URLs.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_not_found":{"value":{"error":{"code":"format_run_not_found","message":"Format run not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"The run has not reached a terminal state, so there is no result to return. `error.code` is `run_not_completed` and `details.status` carries the current status. Poll `status_url` and retry once the run is `completed`, `failed`, `canceled`, or `skipped` — every terminal state returns 200 here, including failures, because the receipt is the answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-runs/{run_id}/cancel":{"post":{"operationId":"cancelFormatRun","summary":"Cancel Format run","tags":["Formats"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Format run receipt plus what this cancel call actually did.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunCancelResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_not_found":{"value":{"error":{"code":"format_run_not_found","message":"Format run not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/format-runs/{run_id}/webhook/redeliver":{"post":{"operationId":"redeliverFormatRunWebhook","summary":"Redeliver Format run webhook","tags":["Formats"],"description":"Re-POSTs this Format run's real `format.run.terminal` payload with a fresh timestamp and `sume-v1` signature. Requires `formats:write`. Works after automatic attempts are exhausted. Does not consume one of the automatic 10 retries. 409 if the run is still running or was created without a webhook_url. A run you cannot see is `404 format_run_not_found`. Missing `formats:write` is `403 insufficient_scope`, never 404.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Updated run `webhook_delivery` after a manual redeliver of that call's real terminal payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRunWebhookRedeliverResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}}}}}},"404":{"description":"The Format or run was not found for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, outside this key's workspace, or addressed at a team handle the key is not a member of; `format_run_not_found` when the run id is unknown or belongs to another owner; `format_run_queue_not_found` when the bulk-run queue id is unknown or belongs to another owner; `previous_run_not_found` when `previous_run_id` names a run that is unknown or belongs to another owner. A workspace member's team key on the correct `{handle}/{slug}` is not this 404 — any key issued in that workspace with `formats:read` / `formats:write` may read and invoke the team Format, not only the user who created the row. All four not-found codes are deliberately indistinguishable from a permission failure — a run you cannot see reads as a run that does not exist. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_run_not_found":{"value":{"error":{"code":"format_run_not_found","message":"Format run not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"The call cannot be redelivered. Stable `error.code` values: `webhook_not_configured` when the job or run was created without a webhook_url, `job_not_terminal` / `run_not_terminal` when it is still running.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}},"/v1/agent/completions":{"post":{"operationId":"createAgentCompletion","summary":"Create Agent Completion","tags":["Agent Completions"],"description":"Runs the Sume Studio Agent — full sandbox, tools, and media generation — on an ad-hoc prompt, unattended. Requires `agent_completions:write`. Supply either `instruction` or `messages` (system/user turns, flattened into one prompt in this version), never both. `generation_spend_cap_credits` is **required**: an unattended agent never runs without a ceiling you chose. `input` stays caller data, never instructions. Attach up to 30 images with top-level `attachments[]` and/or `input_image` parts inside `messages[].content[]` — both use `image_url` (public HTTPS) or `asset_id` (Assets API), and the two sources are merged into one list. Images are fetched and copied into Sume storage at create time, so an unreachable or oversized image fails this call instead of the run, and they compose with `output_schema`. The call is always asynchronous: poll `status_url` / `GET /v1/agent-runs/{run_id}`, or supply `communication.webhook_url` to be sent one signed `agent.run.terminal` POST (see `RunWebhookEvent`) when the run finishes. Webhook delivery is live on both `api.dev.sume.com` and `api.sume.com`. A canceled run never delivers a webhook. Use a Format instead when you have a saved packaged workflow, or the Actions API when you need a schedule or trigger on a saved automation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"instruction":{"type":"string","maxLength":100000},"messages":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["role","content"],"additionalProperties":false,"properties":{"role":{"type":"string","enum":["system","user"]},"content":{"type":["string","array"],"items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["text","input_text","input_image"]},"text":{"type":"string"},"image_url":{"type":"string","format":"uri","maxLength":2048},"asset_id":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","maxLength":180}}}}}}},"model":{"type":"string","enum":["sume-agent"]},"input":{"type":"object","additionalProperties":true},"attachments":{"type":"array","maxItems":30,"items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["input_image"]},"image_url":{"type":"string","format":"uri","maxLength":2048},"asset_id":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","maxLength":180}}}},"generation_spend_cap_credits":{"type":"integer","minimum":0,"description":"Required. Most this run may spend on generation, in credits. `0` is rejected: a run that cannot spend cannot deliver."},"primary_output_key":{"type":"string","maxLength":64},"output_schema":{"$ref":"#/components/schemas/ActionRunOutputSchemaRequest"},"response_format":{"$ref":"#/components/schemas/ActionRunResponseFormatAlias"},"communication":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["async","webhook"],"default":"async","description":"Descriptive only — supplying a URL is what arms delivery. `async` (the default) and `webhook` behave identically."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTPS URL to POST one signed terminal `RunWebhookEvent` to when the run completes or fails (not on cancel). Localhost, private-network, credentialed, and non-HTTPS URLs are rejected with `400 invalid_request`, and the URL is re-validated at delivery time. Delivery is live on both `api.dev.sume.com` and `api.sume.com`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted alias for `webhook_url`, with identical behaviour and the same validation. Send one or the other; sending both with different values is rejected with `400 invalid_request`."}}},"mode":{"type":"string","enum":["async","webhook"],"description":"Accepted top-level alias for `communication.mode`. Normalized into `communication` when present."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.webhook_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Accepted top-level alias for `communication.callback_url`. Normalized into `communication` when present; conflicts with a different nested value return `400 invalid_request`."}}}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Agent Completion receipt with assistant text, artifacts, and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"202":{"description":"Agent Completion receipt with assistant text, artifacts, and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Agent Completion refused on authorization. Stable `error.code` value: `insufficient_scope` when the key lacks `agent_completions:write` or is a service-account key.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Agent Completion submit conflicts. Stable `error.code` value: `idempotency_conflict` when the `Idempotency-Key` was reused with a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/agent-runs":{"get":{"operationId":"listAgentRuns","summary":"List Agent Completion runs","tags":["Agent Completions"],"description":"Lists the authenticated user's Agent Completion runs, newest first. Requires `agent_completions:read`.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Agent Completion runs, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunListResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/agent-runs/{run_id}":{"get":{"operationId":"getAgentRun","summary":"Get Agent Completion run","tags":["Agent Completions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Agent Completion receipt with assistant text, artifacts, and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/agent-runs/{run_id}/status":{"get":{"operationId":"getAgentRunStatus","summary":"Get Agent Completion run status","tags":["Agent Completions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Trimmed Agent Completion run status payload for polling loops.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunStatusResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/agent-runs/{run_id}/result":{"get":{"operationId":"getAgentRunResult","summary":"Get Agent Completion run result","tags":["Agent Completions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Agent Completion receipt with assistant text, artifacts, and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The run has not reached a terminal state, so there is no result to return. `error.code` is `run_not_completed` and `details.status` carries the current status. Poll `status_url` and retry once the run is `completed`, `failed`, `canceled`, or `skipped` — every terminal state returns 200 here, including failures, because the receipt is the answer.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/agent-runs/{run_id}/cancel":{"post":{"operationId":"cancelAgentRun","summary":"Cancel Agent Completion run","tags":["Agent Completions"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"run_id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Agent Completion receipt with assistant text, artifacts, and durable media URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatars":{"get":{"operationId":"listAvatars","summary":"List avatars","tags":["Avatars"],"description":"Lists avatar resource summaries scoped to the authenticated developer workspace. Summaries are currently derived from avatar generation jobs and expose Sume-owned job/result URLs plus sanitized artifact metadata only. The status filter accepts job lifecycle statuses plus `ready`, which maps to completed avatar generation jobs.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["queued","processing","completed","failed","canceled","ready"]},"in":"query","name":"status","required":false,"description":"`ready` is accepted as a resource-friendly alias for completed jobs."},{"schema":{"type":"string"},"in":"query","name":"handle","required":false,"description":"Optional avatar handle filter. Accepts the stored handle with or without @."},{"schema":{"type":"string","enum":["workspace"]},"in":"query","name":"scope","required":false,"description":"`workspace` lists only this workspace's own avatars, without the public catalog."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar resource summaries for the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-catalog/search":{"post":{"operationId":"searchAvatarCatalog","summary":"Search avatar catalog","tags":["Avatars"],"description":"Searches reusable avatars with deterministic text scoring over public-safe metadata and display fields. Results are scoped to public system avatars plus avatars owned by the authenticated workspace. Ranks by lexical score with facet-overlap MMR diversity, and applies source-identity URL dedupe before MMR by default (dedupe=off to disable).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCatalogSearchRequest"},"examples":{"text_query":{"summary":"Text search","value":{"query":"warm skincare creator","limit":10}},"structured_filters":{"summary":"Structured metadata filters","value":{"query":"creator","filters":{"status":"ready","product_category":"beauty","use_case":"beauty_ugc","language":"ko"},"limit":10}},"seeded_explore":{"summary":"Seeded explore browse","value":{"mode":"explore","seed":"session-abc","limit":20,"diversity":0.5}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Ranked public-safe avatar catalog search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCatalogSearchResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatars/{id}":{"get":{"operationId":"getAvatar","summary":"Get avatar","tags":["Avatars"],"description":"Returns a durable avatar resource scoped to the authenticated workspace. Provider-backed image fields are present only after the linked avatar generation job has produced public Sume-hosted artifacts.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or a required runtime ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-videos":{"get":{"operationId":"listAvatarVideos","summary":"List avatar videos","tags":["Avatar Videos"],"description":"Lists avatar-video resource summaries scoped to the authenticated developer workspace. Summaries are currently derived from avatar-video workflow jobs and expose Sume-owned job/result URLs plus sanitized artifact metadata only. The status filter accepts job lifecycle statuses plus `ready`, which maps to completed avatar-video jobs.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["queued","processing","completed","failed","canceled","ready"]},"in":"query","name":"status","required":false,"description":"`ready` is accepted as a resource-friendly alias for completed jobs."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar-video resource summaries for the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoListResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"API-key authentication or the developer API job ledger is not configured or is temporarily unavailable.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/avatar-videos/{id}":{"get":{"operationId":"getAvatarVideo","summary":"Get avatar video","tags":["Avatar Videos"],"description":"Returns a scoped avatar-video resource. Terminal job result fields are public-safe and omit raw provider task URLs.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Avatar-video resource scoped to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/models/sume/avatar-1.0/generate/runs":{"post":{"operationId":"runSumeAvatarGenerateModel","summary":"Run Avatar 1.0 Generate by canonical model id","tags":["Models"],"description":"Canonical model-run alias for Avatar 1.0 Generate. Prefer POST /v1/avatar-1.0/generate for new integrations. Use this path when your client is built around model-run invocation URLs. The legacy alias POST /v1/models/sume/avatar/v1.0/runs remains supported for compatibility.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarModelRunRequest"},"examples":{"prompt_avatar":{"summary":"Create an avatar from a prompt","value":{"avatar_handle":"mina","input":{"type":"prompt","prompt":"A friendly Korean presenter"},"mode":"async"}},"photo_avatar":{"summary":"Create an avatar from a photo URL","value":{"avatar_handle":"uploaded_presenter","input":{"type":"photo","image_url":"https://example.com/inputs/presenter.png"},"mode":"sync","wait_timeout_seconds":20}},"props_avatar":{"summary":"Create an avatar from public props","value":{"avatar_handle":"yuna_creator","input":{"type":"props","ethnicity":"Asian","sex":"female","age":25},"mode":"async"}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Sume-owned model-run submission envelope. Use the returned Sume job URLs for lifecycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRunResponse"},"examples":{"async_queued":{"summary":"Avatar workflow accepted","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"sync","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"202":{"description":"Sume-owned model-run submission envelope. Use the returned Sume job URLs for lifecycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRunResponse"},"examples":{"async_queued":{"summary":"Avatar workflow accepted","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":null}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"model":"sume/avatar/v1.0","request_id":"req_0123456789abcdef0123456789abcdef","avatar_id":"avtr_0123456789abcdef","avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null,"run":{"id":"req_0123456789abcdef0123456789abcdef","object":"model_run","model":"sume/avatar/v1.0","status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false},"resources":{"avatar":{"id":"avtr_0123456789abcdef","status":"processing","resource_status":"processing","type":"prompt","source_type":"prompt","handle":"studio_presenter","preview_image_url":null,"preview_video_url":null,"artifacts":[],"error":null,"created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","ready_at":null,"failed_at":null,"archived_at":null,"job":{"id":"job_0123456789abcdef","status":"queued","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"},"job_status":"queued"},"avatar_video":null},"output":null,"steps":[{"id":"avatar","type":"avatar_generation","status":"processing","resource_id":"avtr_0123456789abcdef","request_id":"req_0123456789abcdef0123456789abcdef","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}],"job":{"id":"job_0123456789abcdef","type":"video_generation","status":"queued","model":"sume/avatar/v1.0","communication_mode":"sync","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","idempotency_hit":false,"usage":{"credits":20},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar model-run submit conflicts. Possible stable `error.code` values: `avatar_handle_taken`, `avatar_handle_reserved`, `idempotency_conflict`, or `avatar_not_ready` when creating a video from an existing avatar that is not ready.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_handle_taken":{"summary":"Handle already exists","value":{"error":{"code":"avatar_handle_taken","message":"Avatar handle @studio_presenter is already in use.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_handle_taken","next_action":"fix_input","details":{"handle":"studio_presenter","avatar_id":"avtr_0123456789abcdef"}}}},"avatar_handle_reserved":{"summary":"Handle prefix is reserved","value":{"error":{"code":"avatar_handle_reserved","message":"@sume_presenter uses the reserved sume_ avatar handle prefix. Choose a non-reserved handle for user-created avatars.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_handle_reserved","next_action":"fix_input","details":{"handle":"sume_presenter","reserved_prefix":"sume_","reserved_for":"system_avatars"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/avatar-1.0/generate/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"mina\",\n  \"input\": {\n    \"type\": \"prompt\",\n    \"prompt\": \"A friendly Korean presenter\"\n  },\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/models/sume/avatar-1.0/talking-video/runs":{"post":{"operationId":"runSumeAvatarTalkingVideoModel","summary":"Run Avatar 1.0 Talking Video by canonical model id","tags":["Models"],"description":"Canonical model-run alias for Avatar 1.0 Talking Video. Prefer POST /v1/avatar-1.0/talking-video for new integrations. Use this path when your client is built around model-run invocation URLs. The legacy alias POST /v1/models/sume/avatar-video/v1.0/runs remains supported for compatibility.\n\nGeneration flow: `mode: async` returns immediately with `status_url`, `result_url`, `events_url`, and `cancel_url` while cancellation is still available. `mode: sync` and `mode: subscribe` are aliases for the same bounded wait of up to `wait_timeout_seconds` (max 30); if the job is still queued or the per-process waiter budget is full, the response includes `sync.timed_out` or `sync.capacity_exhausted` and clients should poll `status_url` rather than resubmit. That 30-second ceiling bounds the HTTP wait, not the job, so clients that need a longer wait should submit with `async` and poll from their own side. `/result` returns `409 job_not_completed` until `result_ready` is true. Terminal callbacks are delivered to `webhook_url` as signed WebhookEvent payloads when configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoCreateRequest"},"examples":{"avatar_video_model_run":{"summary":"Run Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","script":"Share a quick product benefit in one concise sentence.","product_image":"https://example.com/inputs/product.png","scene":{"type":"prompt","prompt":"Bright product demo set"},"quality":"max","aspect_ratio":"9:16","mode":"async"}},"productless_avatar_video_model_run":{"summary":"Run productless Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","script":"Share a quick update in one concise sentence.","quality":"plus","mode":"sync","wait_timeout_seconds":20}},"multi_scene_avatar_video_model_run":{"summary":"Run multi-scene Avatar Video 1.0","value":{"avatar_handle":"sume_clawra","aspect_ratio":"9:16","quality":"plus","mode":"async","video_inputs":[{"id":"hook","voice":{"type":"text","script":"Wait, this turned one selfie into a whole video?","duration":3},"background":{"type":"prompt","prompt":"Casual bedroom or couch background, selfie-camera framing, native UGC lighting."}},{"id":"demo","voice":{"type":"text","input_text":"You pick a template, drop in your photo, and it builds the clip around you.","duration":5},"background":{"type":"prompt","prompt":"Casual bedroom or couch background, selfie-camera framing, native UGC lighting."}}]}}}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"202":{"description":"Queued avatar-video resource and generic job envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarVideoSubmitResponse"},"examples":{"async_queued":{"summary":"Avatar-video resource queued","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":null,"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}},"sync_capacity_exhausted":{"summary":"Sync waiter capacity exhausted; poll instead","value":{"data":{"request_id":"job_0123456789abcdef","job":{"id":"job_0123456789abcdef","type":"avatar_video","status":"queued","model":"sume/avatar-video/v1.0","communication_mode":"async","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","started_at":null,"completed_at":null,"canceled_at":null,"api_key":{"id":"dak_0123456789abcdef","prefix":"sume_live_"},"preview_image_url":null,"scene":null,"scene_previews":null,"result":null,"error":null,"webhook_delivery":null},"status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result","events_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/events","cancel_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/cancel","cancelable":true,"next_action":"poll_status","next_poll_after_seconds":2,"recommended_poll_interval_seconds":2,"retry_after_seconds":null,"result_ready":false,"terminal":false,"idempotency_hit":false,"usage":{"credits":20},"generation_limits":{"tier":"startup","plan_id":"startup","limit_source":"plan","purchased_credits_last_4_weeks":0,"purchased_concurrency_limit":4,"purchased_queued_jobs_limit":20,"plan_concurrency_limit":4,"plan_queued_jobs_limit":20,"concurrency_limit":4,"queued_jobs_limit":20,"admin_override_expires_at":null,"accepted_generation_jobs_limit":24,"active_generation_jobs":1,"queued_generation_jobs":0,"accepted_generation_jobs":1,"queue_capacity_remaining":23,"wave_size_hint":17},"sync":{"wait_timeout_seconds":20,"completed":false,"terminal":false,"succeeded":false,"failed":false,"canceled":false,"result_ready":false,"timed_out":true,"capacity_exhausted":true},"avatar_video_id":"avv_0123456789abcdef","avatar_video":{"id":"avv_0123456789abcdef","avatar_id":"avtr_0123456789abcdef","request_id":"job_0123456789abcdef","status":"queued","resource_status":"processing","job_status":"queued","created_at":"2026-06-27T00:00:00.000Z","updated_at":"2026-06-27T00:00:00.000Z","completed_at":null,"video_url":null,"preview_image_url":null,"scene":null,"scene_previews":null,"artifacts":[],"metadata":null,"captions":null,"result":null,"error":null}}}}}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"The authenticated workspace has an issued balance row but not enough balance for this request. `details.required_usd` is what the request needs in dollars (rounded up to the cent), `details.available_usd` what the workspace can spend now (rounded down); `details.required_credits` / `details.available_credits` carry the same amounts in credits for older clients. A Sume API key (Settings → API keys, or open.sume.com) gets `insufficient_funds` instead, in dollars only, on every host and for a team workspace too; other credentials get `insufficient_credits`, or `organization_wallet_not_provisioned` for a team workspace that has no wallet yet. Nothing is charged, and the refusal keeps its answer for its `Idempotency-Key`: top up, then send a new request.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The requested resource was not found in this workspace.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Avatar-video submit conflicts. Possible stable `error.code` values: `avatar_not_ready` when the referenced avatar is not ready, or `idempotency_conflict` when the Idempotency-Key was reused for a different payload.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"avatar_not_ready":{"summary":"Referenced avatar is not video-ready","value":{"error":{"code":"avatar_not_ready","message":"Avatar is not ready for video generation.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":false,"retry_after_seconds":null,"public_reason":"avatar_not_ready","next_action":"inspect_events","details":{"avatar_id":"avtr_0123456789abcdef","status":"processing"}}}},"idempotency_conflict":{"summary":"Idempotency key payload mismatch","value":{"error":{"code":"idempotency_conflict","message":"Idempotency-Key was already used for a different job operation or payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"retry_after_seconds":null,"public_reason":"idempotency_conflict","next_action":"fix_input","details":{"job_id":"job_0123456789abcdef","job_type":"avatar_video","job_status":"processing","status_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/status","result_url":"https://api.sume.com/v1/jobs/job_0123456789abcdef/result"}}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Sume could not start the generation job. No result is available yet.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The generation runtime is unavailable because a required component is not configured or dispatch capacity is exhausted. No external generation job is started when the runtime is not configured. Capacity exhaustion returns retry-safe job metadata and no internal execution details.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x20-\\x7E]+$"},"example":"job-retry-2026-06-27-001","description":"Optional retry safety key for paid job creation. Reusing the same key with the same operation and normalized payload returns the original job with `idempotency_hit: true`; reusing it for a different operation or payload returns `409 idempotency_conflict`, whose `error.details` names the job that already holds the key (`job_id`, `job_type`, `job_status`, `status_url`, `result_url`) so you can adopt it instead of re-creating under a new key. The key itself is never echoed in an error body, but it is returned as `idempotency_key` on every job object, so it doubles as the label you join on when rebuilding which job was which. Send one on every paid create you might retry: a failed response proves the work was refused only when it names a validation, authorization or balance reason, and a `5xx` never does — with a key, the retry adopts whatever the first call created instead of paying for it twice."}],"callbacks":{"webhook_url":{"{$request.body#/webhook_url}":{"post":{"summary":"Receive Sume terminal job callback","description":"Receiver contract: Sume sends terminal job callbacks as JSON. Verify the raw body with `x-sume-webhook-timestamp` and `x-sume-webhook-signature` (`sume-v1`). Return any 2xx response after durable processing. Network errors and non-2xx responses are retried up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt, and are recorded under `webhook_delivery`; exhausted attempts remain inspectable through job readback/events and leave the job at its real terminal state.","parameters":[{"name":"x-sume-webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"example":"1780000000","description":"Unix timestamp seconds for replay protection. Verify within your receiver tolerance window."},{"name":"x-sume-webhook-signature","in":"header","required":true,"schema":{"type":"string"},"example":"sume-v1,t=1780000000,v1=<hex_signature>","description":"HMAC signature over timestamp and raw body. Current signature version is `sume-v1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"examples":{"completed":{"summary":"Completed job","value":{"event":"job.completed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"OK","payload":{"preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt","status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png"},"scene_previews":[{"index":0,"status":"ready","preview_image_url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","scene":{"type":"prompt"}}],"artifacts":[{"id":"artf_0123456789abcdef0123456789abce","public_artifact_id":"artf_0123456789abcdef0123456789abce","visibility":"public_by_link","stage":"first_frame","type":"image","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abce/first-frame.png","content_type":"image/png","size_bytes":123456,"width":720,"height":1280,"duration_ms":null,"checksum_sha256":null},{"id":"artifact_0123456789abcdef","public_artifact_id":"artf_0123456789abcdef0123456789abcd","visibility":"public_by_link","type":"video","url":"https://media.sume.com/artifacts/artf_0123456789abcdef0123456789abcd/video.mp4","content_type":"video/mp4","size_bytes":1234567,"width":1280,"height":720,"duration_ms":5000,"checksum_sha256":null}]},"error":null}},"failed":{"summary":"Failed job","value":{"event":"job.failed","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"generation_failed","message":"Generation failed.","category":"generation_rejected","stage":"generation_processing","retryable":false,"retry_after_seconds":null,"public_reason":"generation_rejected","next_action":"inspect_events"}}},"canceled":{"summary":"Canceled job","value":{"event":"job.canceled","request_id":"job_0123456789abcdef","job_id":"job_0123456789abcdef","status":"ERROR","payload":null,"error":{"code":"job_canceled","message":"Job was canceled before completion.","category":"internal","stage":"cancellation","retryable":false,"retry_after_seconds":null,"public_reason":"job_canceled","next_action":"inspect_events"}}}}}}},"responses":{"200":{"description":"Delivered. Any 2xx response marks the callback successful."},"204":{"description":"Delivered with no response body. Any 2xx response marks the callback successful."},"400":{"description":"Receiver rejected the callback. Sume records the attempt and retries until the 10-attempt cap is exhausted."},"500":{"description":"Receiver failed. Sume records the attempt and retries until the 10-attempt cap is exhausted."}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Submit async job","source":"curl -X POST https://api.sume.com/v1/models/sume/avatar-1.0/talking-video/runs \\\n  -H 'Authorization: Bearer <your_sume_api_key>' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: demo-retry-safe-job-001' \\\n  -d '{\n  \"avatar_handle\": \"sume_clawra\",\n  \"script\": \"Share a quick product benefit in one concise sentence.\",\n  \"product_image\": \"https://example.com/inputs/product.png\",\n  \"scene\": {\n    \"type\": \"prompt\",\n    \"prompt\": \"Bright product demo set\"\n  },\n  \"quality\": \"max\",\n  \"aspect_ratio\": \"9:16\",\n  \"mode\": \"async\"\n}'"},{"lang":"Shell","label":"Poll status and fetch result","source":"curl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/status'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/result'\ncurl -H 'Authorization: Bearer <your_sume_api_key>' 'https://api.sume.com/v1/jobs/job_0123456789abcdef/events'"}]}},"/v1/skills/{slug}/contents/{path}":{"get":{"operationId":"getSkillContent","summary":"Get a skill file","tags":["Skills"],"description":"Returns one file of a first-party skill package as a GitHub file object (`encoding: \"base64\"` plus `content`), or, when the path names a directory, the entries under it.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"path","name":"path","required":true,"description":"Package-relative file or directory path, e.g. `SKILL.md` or `references/models.md`."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Format package file, or the entries under a directory or the package root.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Nothing was found at this address. Stable `error.code` values: `skill_not_found` when no first-party skill has this slug in this environment, and `skill_content_not_found` when the skill exists but has no file or directory at the path.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/formats/{handle}/{slug}/contents/{path}":{"get":{"operationId":"getFormatContent","summary":"Get a Format package file","tags":["Formats"],"description":"Returns one package file as a GitHub file object — `encoding: \"base64\"` plus `content` — or, when the path names a package directory, the entries under it. Requires `formats:read`. Keep the returned `sha`: it is the precondition `PUT` and `DELETE` require to replace or remove that file.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"path","name":"path","required":true,"description":"Package-relative file or directory path, e.g. `SKILL.md` or `references/plan.md`."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"One Format package file, or the entries under a directory or the package root.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentsResponse"}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Read refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:read` (`details.required_scope` names it — mint a new key; scopes cannot be patched onto an existing one), and on vanity `{handle}/{slug}` routes also `workspace_key_required` when the caller is a member of the team workspace but the key was not issued there. Missing scopes never answer `404 format_not_found`. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope_read":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:read"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"Nothing was found at this address for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, or outside the calling key's workspace, and `format_content_not_found` when the Format exists but holds no file or directory at that path. Both are deliberately indistinguishable from a permission failure. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_content_not_found":{"value":{"error":{"code":"format_content_not_found","message":"No file or directory at \"references/plan.md\" in this Format package.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The Studio Agent control plane that owns Format and run state is unreachable or not configured for this environment. Stable `error.code` value: `studio_agent_upstream_unavailable`. This is a Sume-side condition — the API key is not at fault, and re-issuing it will not help.\n\nOn a run-create route this status can also mean the control plane did not answer in time, in which case `public_reason` is `studio_agent_upstream_timeout`, `retryable` is `true`, and `details.retry_with_idempotency_key` is set. The run may already exist and may already be spending: always send `Idempotency-Key` on run create, and retry with the same value, which replays the existing run instead of creating a second one.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"put":{"operationId":"putFormatContent","summary":"Create or replace a Format package file","tags":["Formats"],"description":"Writes one file into a Format's package and commits it, the same way GitHub's `PUT /repos/{owner}/{repo}/contents/{path}` does. Requires `formats:write`. `content` is the whole new file, base64-encoded — this is a replace, not a patch. `sha` is required when the path already exists and must be the blob sha from a prior `GET`; omit it to create a new file. The commit's author is the key's owner: a client-supplied `author` or `committer` is ignored. The Format's stored package, its `package_sha`, and its display `version` all move with the commit. Package rules still apply — at most one directory deep under `references/` or `agents/`, `SKILL.md` frontmatter `name` matching the slug, and the per-file and whole-package byte caps — and a rejected package is never committed. If package history cannot take the commit the write fails with `503 format_git_unavailable` rather than saving a Format whose commit sha nobody can resolve. Send `If-Match: <package_sha>` to add a whole-package precondition on top of the per-file `sha`. To write several files as one commit, use `PUT /v1/formats/{handle}/{slug}/contents`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentPutRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"path","name":"path","required":true,"description":"Package-relative file or directory path, e.g. `SKILL.md` or `references/plan.md`."},{"schema":{"type":"string","pattern":"^[0-9a-f]{40}$"},"in":"header","name":"if-match","required":false,"description":"Package precondition: the Format's `package_sha` (the `commit.tree.sha` of the write you last read). The write is refused with `409 format_package_sha_mismatch` if the package has moved since. Ignored on Formats published before `package_sha` existed, which carry none. Omit it to rely on per-file `sha` alone."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"The file after the write and the commit it produced.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentWriteResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_authoring_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot edit Format packages.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_authoring_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"Nothing was found at this address for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, or outside the calling key's workspace, and `format_content_not_found` when the Format exists but holds no file or directory at that path. Both are deliberately indistinguishable from a permission failure. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_content_not_found":{"value":{"error":{"code":"format_content_not_found","message":"No file or directory at \"references/plan.md\" in this Format package.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"The write was refused because the caller's view of the package is stale. Stable `error.code` values: `format_content_sha_required` when the path already exists and no `sha` was sent, `format_content_sha_mismatch` when the `sha` does not match the stored file (or names a path that does not exist), `format_package_sha_mismatch` when the `If-Match` package sha is not the Format's current one, `format_authoring_in_progress` while an AI-authored Format is still being written, and `skill_slug_taken` / `skill_slug_reserved` from package validation. Re-read `GET …/contents/{path}` and retry with the returned `sha`; `format_package_sha_mismatch` carries the current package sha in `error.details.package_sha`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"413":{"description":"Request body exceeds the configured API limit.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"value":{"error":{"code":"payload_too_large","message":"Request body exceeds the configured API limit.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"payload_too_large","next_action":"fix_input","retry_after_seconds":null,"details":{"limit_bytes":4194304}}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The write was refused rather than saved without a commit. Stable `error.code` values: `format_git_unavailable` when Format package history is unreachable or not configured for this environment, and `studio_agent_upstream_unavailable` when the control plane itself could not be reached. Nothing was changed; retry.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}},"delete":{"operationId":"deleteFormatContent","summary":"Delete a Format package file","tags":["Formats"],"description":"Removes one file from a Format's package and commits it, like GitHub's `DELETE /repos/{owner}/{repo}/contents/{path}`. Requires `formats:write`. Both `message` and `sha` are required; `sha` must be the blob sha from a prior `GET`. `data.content` comes back `null`, as GitHub returns it. `SKILL.md` cannot be deleted — every package must keep its entry file, so that request is a `400`. `If-Match: <package_sha>` applies here too.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentDeleteRequest"}}}},"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":39},"in":"path","name":"handle","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"slug","required":true},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"path","name":"path","required":true,"description":"Package-relative file or directory path, e.g. `SKILL.md` or `references/plan.md`."},{"schema":{"type":"string","pattern":"^[0-9a-f]{40}$"},"in":"header","name":"if-match","required":false,"description":"Package precondition: the Format's `package_sha` (the `commit.tree.sha` of the write you last read). The write is refused with `409 format_package_sha_mismatch` if the package has moved since. Ignored on Formats published before `package_sha` existed, which carry none. Omit it to rely on per-file `sha` alone."}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"The file after the write and the commit it produced.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, for the budget this request spent from. Reads and writes are separate budgets. The plan sets the write number — Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min — and the read budget defaults to 40x that (Free 4800/min), so polling cannot exhaust your own submits. Uncredentialed requests are bucketed per client IP at the Free write rate with a 4x read budget."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window, for the budget this request spent from. A 429 names that budget in error.details.scope (read or write)."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatContentWriteResponse"}}}},"400":{"description":"Invalid request body, parameters, query string, or communication options.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown_parameter":{"value":{"error":{"code":"unknown_parameter","message":"Unknown parameter: 'webook_url'. Did you mean 'webhook_url'?","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"unknown_parameter","next_action":"fix_input","retry_after_seconds":null,"details":{"errors":[{"path":"webook_url","loc":["webook_url"],"message":"Unrecognized request field.","type":"unknown_parameter","suggestion":"webhook_url"}]}}}}}}}},"401":{"description":"Missing, malformed, revoked, or invalid API key. Send either `x-api-key` or `Authorization: Bearer`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"Missing API key. Send x-api-key or Authorization: Bearer.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"authentication_required","next_action":"authenticate","retry_after_seconds":null}}}}}}},"403":{"description":"Format run refused on authorization. Stable `error.code` values: `insufficient_scope` when the key lacks `formats:write` (`details.required_scope`) or is a service-account key (`details.reason` is `service_account_format_runs_unsupported`), and `workspace_key_required` when the Format belongs to a team workspace and the call used a key from another workspace — create a key inside that workspace and retry. `details.workspace_id` names the workspace on `workspace_key_required`. Missing scopes never answer `404 format_not_found`; scopes cannot be patched onto an existing key — mint a new one. `next_action` is `authenticate`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"error":{"code":"insufficient_scope","message":"This API key does not have permission to access this endpoint.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"required_scope":"formats:write"}}}},"service_account_format_authoring_unsupported":{"value":{"error":{"code":"insufficient_scope","message":"Service-account keys cannot edit Format packages.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"insufficient_scope","next_action":"authenticate","retry_after_seconds":null,"details":{"reason":"service_account_format_authoring_unsupported"}}}},"workspace_key_required":{"value":{"error":{"code":"workspace_key_required","message":"This Format belongs to a team workspace. Use an API key created in that workspace.","request_id":"req_0123456789abcdef0123456789abcdef","category":"auth","stage":"auth","retryable":false,"public_reason":"workspace_key_required","next_action":"authenticate","retry_after_seconds":null,"details":{"workspace_id":"ws_0123456789abcdef"}}}}}}}},"404":{"description":"Nothing was found at this address for this key. Stable `error.code` values: `format_not_found` when the Format is unknown, archived, or outside the calling key's workspace, and `format_content_not_found` when the Format exists but holds no file or directory at that path. Both are deliberately indistinguishable from a permission failure. Missing `formats:read` / `formats:write` is `403 insufficient_scope`, never this 404.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"format_not_found":{"value":{"error":{"code":"format_not_found","message":"Format not found.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}},"format_content_not_found":{"value":{"error":{"code":"format_content_not_found","message":"No file or directory at \"references/plan.md\" in this Format package.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"resource_not_found","next_action":"fix_input","retry_after_seconds":null}}}}}}},"409":{"description":"The write was refused because the caller's view of the package is stale. Stable `error.code` values: `format_content_sha_required` when the path already exists and no `sha` was sent, `format_content_sha_mismatch` when the `sha` does not match the stored file (or names a path that does not exist), `format_package_sha_mismatch` when the `If-Match` package sha is not the Format's current one, `format_authoring_in_progress` while an AI-authored Format is still being written, and `skill_slug_taken` / `skill_slug_reserved` from package validation. Re-read `GET …/contents/{path}` and retry with the returned `sha`; `format_package_sha_mismatch` carries the current package sha in `error.details.package_sha`.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"run_not_completed":{"value":{"error":{"code":"run_not_completed","message":"Format run result is not available until the run is terminal.","request_id":"req_0123456789abcdef0123456789abcdef","category":"job_state","stage":"job_state","retryable":true,"public_reason":"run_not_completed","next_action":"poll_status","retry_after_seconds":2,"details":{"status":"processing"}}}},"idempotency_conflict":{"value":{"error":{"code":"idempotency_conflict","message":"Idempotency key reused with a different payload.","request_id":"req_0123456789abcdef0123456789abcdef","category":"validation","stage":"validation","retryable":false,"public_reason":"idempotency_conflict","next_action":"fix_input","retry_after_seconds":null}}}}}}},"429":{"description":"Too many requests for the current API key/client IP bucket, a generation queue capacity rejection, or a fail-closed rate-limit store degradation. Reads and writes have separate per-key budgets and `details.scope` names which one ran out. The workspace subscription plan sets the write budget: Free 120/min, Pro 300/min, Startup 600/min, Scale 1200/min, Enterprise by arrangement. The read budget defaults to 40x the write budget (Free 4800/min), so a status-poll loop cannot 429 the submits that spawned it. Unauthenticated requests are limited per client IP at the Free write rate with a 4x read budget.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."},"ratelimit-limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed in the current window, set by the workspace subscription plan."},"ratelimit-remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until the current rate-limit window resets."},"retry-after":{"schema":{"type":"integer"},"description":"Seconds clients should wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many API requests. Retry later.","request_id":"req_0123456789abcdef0123456789abcdef","category":"rate_limit","stage":"queue","retryable":true,"public_reason":"rate_limited","next_action":"retry_later","retry_after_seconds":1}}}}}}},"500":{"description":"Unexpected server error.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Unexpected server error.","request_id":"req_0123456789abcdef0123456789abcdef","category":"internal","stage":"internal","retryable":true,"public_reason":"internal_error","next_action":"contact_support","retry_after_seconds":null}}}}}}},"503":{"description":"The write was refused rather than saved without a commit. Stable `error.code` values: `format_git_unavailable` when Format package history is unreachable or not configured for this environment, and `studio_agent_upstream_unavailable` when the control plane itself could not be reached. Nothing was changed; retry.","headers":{"x-sume-request-id":{"schema":{"type":"string","pattern":"^req_[a-f0-9]{32}$"},"description":"Sume-owned HTTP request correlation id. Include this value when contacting support. It is separate from generation job `request_id` values."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"studio_agent_upstream_unavailable":{"value":{"error":{"code":"studio_agent_upstream_unavailable","message":"The Format runtime is temporarily unavailable.","request_id":"req_0123456789abcdef0123456789abcdef","category":"runtime_unavailable","stage":"runtime","retryable":false,"public_reason":"studio_agent_upstream_unavailable","next_action":"contact_support","retry_after_seconds":null}}}}}}}}}}},"servers":[{"url":"https://api.sume.com","description":"Sume API"}],"x-sume-generation-flow":{"polling":{"submit":"POST a generation route with mode async or omit mode.","poll":"GET status_url until terminal is true or result_ready is true.","result":"GET result_url after result_ready is true; non-completed jobs return 409 job_not_completed.","events":"GET events_url for sanitized lifecycle, generation, terminal, and webhook delivery events.","cancel":"POST cancel_url while cancelable is true. Cancellation is only accepted before external generation work starts."},"admission":{"primary_limit":"workspace_generation_concurrency","tier_source":"Paid credits purchased in the last four weeks. Operator grants and legacy balances do not increase concurrency. Admin overrides can raise effective limits without creating purchase records.","queue_full":"If the workspace's pending capacity (queued-job budget plus idle concurrency seats) is consumed, Sume rejects new paid generation submissions with 429 queue_full after refunding any reservation. Work submitted while all concurrency seats are busy is accepted into the queue as long as the queued-job budget remains.","public_metadata":"Accepted generation responses include generation_limits with Sume-owned tier, concurrency, queue, active, queued, and remaining capacity fields."},"sync":{"modes":["sync","subscribe"],"aliases":"sync and subscribe select the same bounded waiter and return the same envelope. subscribe is not a long-lived subscription, an event stream, a progress feed, or a longer wait, and is unrelated to the SDK's subscribeFormatRun or to a run's communication.mode.","wait_timeout_seconds":"0 to 30 seconds. Bounds the HTTP wait, not the job duration. Submit with mode async and poll for anything that can outlast it.","capacity_exhausted":"True when Sume skips blocking wait because the waiter budget is full; clients should poll status_url.","timed_out":"True when the response returned before the job reached a terminal state, including when the wait was skipped for capacity.","exhausted_wait":"Still 2xx and still carries the job id. Continue with status_url honoring next_poll_after_seconds; reuse the same Idempotency-Key if you retry the submit itself, and never create a second paid job for the same intent."},"webhooks":{"destinations":["webhook_url"],"event_schema":"WebhookEvent","headers":["x-sume-webhook-timestamp","x-sume-webhook-signature","x-sume-webhook-secret-fingerprint"],"signature_version":"sume-v1","receiver_responses":"Any 2xx response marks delivery successful. Network errors and non-2xx responses retry up to 10 attempts total, spaced by a fixed delay (30s by default) with a 10s timeout per attempt. Exhausting them fails the delivery, not the job.","events":["job.completed","job.failed","job.canceled"]},"status_vocabulary":{"job_statuses":["queued","processing","completed","failed","canceled"],"resource_statuses":["processing","ready","failed","canceled","archived"],"mapping":{"queued":"processing","processing":"processing","completed":"ready","failed":"failed","canceled":"canceled"}},"redaction":"Public API responses and examples omit raw provider task ids, raw provider URLs, signed URLs, secrets, and private database identifiers."}}