API Surface and SDK

Appendix C API Surface and SDK This appendix summarizes how clients integrate with the production ScryptedAI HTTP API and the draft Python and TypeScript SDKs that sit on top of it. It complements the orchestration and billing chapters (Chapters 6 and 7) and the machine-generated capability inventory (Appendix B). For every request and response field, the authoritative contract remains the running service’s OpenAPI document. C.1 HTTP API overview The API is implemented as a FastAPI application (main.py) exposing versioned REST resources under a single host (default production base URL https://api.scrypted.ai ). Capabilities fall into a few recurring families: Accounts Permissionless account creation, balance read, funding, and account metadata (/accounts and related routes). Generation and media Text, image, video, audio, embeddings, forecasts, and orchestrated video workflows (/gen erate/…, /generation/…, /generations/…). Recipes and jobs Discovery of recipe or ingredient interfaces (schemas only), generic execution by registry id, and asynchronous job lifecycle (/recipes/…, /jobs/…). Safety and analysis Text moderation assessments, structured image/video analysis, and motion analysis (/mod erations/…, /analysis/…). Tooling and webhooks Video utilities (e.g. stitch, extend), provider webhooks, and health checks (/generate/vi deo/tool/…, /webhooks/…, /healthz). Long-running work is modeled as jobs: clients submit a request, receive a job identifier, and poll or subscribe for completion (see Chapter 6). Many routes accept an optional webhook URL and secret so the server can push terminal state instead of polling. C.2 Machine-readable surface and path catalog The service publishes OpenAPI at /openapi.json and interactive docs at /docs (and /redoc when enabled). Internal or operator-only routes may be omitted from public documentation 132

builds; the OpenAPI snapshot from a local or staging process should be treated as the contract for that deployment. The repository maintains a generated path catalog for SDKs: • sdk/common/api_catalog.json — maps stable string keys (e.g. generations_text_nova_pro) to relative paths (e.g. /generations/text/nova-pro), plus HTTP methods per path. • Built by scripts/build_sdk_api_catalog.py from the app’s OpenAPI, optional httpPath / sdkEndpointKey fields on avb.json sidecars, and sparse overrides in sdk/common/catal og_path_to_sdk_key.json. Regenerate the catalog after route or AVB changes: python scripts/build_sdk_api_catalog.py Appendix B lists registry slugs and, where declared, the same httpPath values used to bind capabilities into this catalog. C.3 Authentication, idempotency, and payments Bearer tokens. Authenticated calls send Authorization: Bearer <token>. Tokens are issued on account creation (POST/accounts) and use the scrypted_ prefix convention (see sdk/python/src/scryptedai/constants.py). Idempotency. Account creation and other sensitive operations may require an Idempotency-Key header so retries do not create duplicate resources. The SDK exposes a typed idempotency key generator for this purpose. x402 and X-PAYMENT. When an account lacks balance for a paid operation, the API may respond with 402 Payment Required and a machine-readable payment challenge (Chapter 7). Clients complete payment out-of-band and retry with an X-PAYMENT header carrying the settlement payload. The Python SDK includes an X402PaymentHandler; funding flows use POST/accounts/funding. C.4 Execution patterns Dedicated capability routes. Many registry-backed workflows expose a first-class POST route with a typed request body (e.g. POST/generations/images/flux-2-pro, POST/mod erations/text/assessments). These are the paths recorded in api_catalog.json and, for graphs, often mirrored in recipes/*.avb.json as httpPath. Generic recipe and ingredient execution. Any registered recipe or atomic ingredient may be invoked with: POST/recipes/{recipe_id} where recipe_id is the full registry string (including colons), URL-encoded. The same pattern supports GET /recipes/{recipe_id} for interface metadata (input/output JSON schemas) without exposing internal DAG structure. The Python method ScryptedClient.invoke_recipe performs encoding and POST. 133

Legacy wrapper. POST/generate/recipe remains as a compatibility surface for older clients; new integrations should prefer /recipes/… or a dedicated generation route where one exists. C.5 Client SDKs Two draft SDKs share the same path catalog and exception taxonomy. They are suitable for automation, internal tools, and as references for hand-written HTTP clients. C.5.1 Python SDK • Install: editable install from the repo root, e.g. pip install -e sdk/python, so sdk/comm on/api_catalog.json resolves correctly. • Entry type: ScryptedClient (sdk/python/src/scryptedai/client.py) with base_url, bearer_token, timeout, and retry options. • Account flows: create_account() (adopts returned token), get_account_info(), async fund_account(…) with x402 handling. • Recipes: get_recipe_interface(recipe_id), invoke_recipe(…) with optional idempotency and webhook parameters. • Catalog helpers: path_for_endpoint_key, list_node_keys, list_workflow_keys in sdk/python/src/scryptedai/_catalog.py. • Errors: hierarchy under ScryptedError (authentication, payment, validation, rate limit, network, timeout). Examples for specific recipes live under sdk/python/examples/. C.5.2 TypeScript SDK • Package: Node-oriented client with undici-based HTTP, keep-alive defaults, and the same logical methods as Python (create account, account info, recipe interface, invoke recipe, job helpers where implemented). • Configuration: sdk/typescript/src/constants.ts consumes the shared catalog; build pipelines should ensure api_catalog.json is present before compilation. C.5.3 Reference snippet outside the SDK tree The file docs/reference-code/sdk/python/scrypted.py is a standalone example client (Nova-oriented chat and alignment scoring) and is not the same as the installable scryptedai package; cite it only as sample code. C.6 Operational expectations • Timeouts and retries: The SDKs default to a 30 s timeout and bounded exponential backoff on transient failures; long video or orchestration jobs require polling job status, not blocking on the initial POST. • Rate limits: Application-level rate-limit constants exist in the codebase (Chapter 9); enforcement may be delegated to edge infrastructure. Clients should honor 429 and Retry-After when present. 134

• Versioning: The HTTP API version string in OpenAPI may lag feature additions; trust route presence in OpenAPI and the generated api_catalog.json for a given commit or deployment tag. For a line-by-line list of ingredients and recipes (including optional HTTP path lines in the PDF), see Appendix B. 135

Source: transcribed from the compiled Scrypted Network Design whitepaper PDF for web reading. Layout, figures, and pagination may differ from the PDF.