Skip to main content
The AI Studio API is served from https://ai.tuturuuu.com and accepts workspace-scoped ttr_ai_ credentials through the standard bearer header:
The plaintext credential is shown once. Store it in a secret manager and never place it in browser bundles, URLs, logs, or source control.
For a workspace-aware quickstart with copyable cURL and server-side TypeScript examples, open AI Studio, select a workspace, and choose Developer docs. That module links directly to the same workspace’s keys, Playground, credits, and run observability.
Creating or rotating a credential requires both the workspace manage_ai_keys permission and a standing platform-admin approval for that workspace. Listing and revoking existing credentials remain available without issuance approval. Removing approval does not invalidate existing credentials. Registered external apps may instead use a short-lived ttr_app_ access token. The app registration and issued token must both include workspace:session and ai:use; speech requests require tts:use. These requests must also send the normalized workspace ID returned by the app-token exchange:
The external-app path is temporarily exempt from workspace credit deductions. It is not unrestricted access: registration status, linked workspace, current user membership, model policy, payload bounds, workspace request rate, stable request IDs, and usage auditing remain enforced. Browser sessions, internal satellite sessions, ordinary Studio keys, and unrecognized callers never receive this exemption.

​
OpenAI-compatible endpoints

Requests support stable x-request-id values and the idempotency-key header. Streaming responses use server-sent events. Errors use an OpenAI-compatible error object and include the stable request ID for support correlation. Model access is the intersection of the globally enabled catalog, global Studio defaults, workspace policy, plan or root grants, and the key’s own model restrictions. A model visible elsewhere in Tuturuuu is not necessarily available to a Studio key. The legacy global/workspace Studio enablement switches no longer gate model execution. Credit availability, model policy, credential status, budgets, rate limits, and abuse controls remain authoritative.

​
Structured output and audit attribution

Chat completions preserve response_format values text, json_object, and json_schema through to the model. For schema output, include json_schema.name and json_schema.schema; schemas are bounded to 100,000 characters. Set an explicit max_completion_tokens budget for large structured results. The default is 2,048 tokens and the maximum is 32,768; a truncated response still incurs provider usage even when the calling application cannot parse it. Applications may attach X-Tuturuuu-Operation and X-Tuturuuu-Entity-Id headers for audit correlation. A valid operation is also shown as the run feature in AI Studio, so operators can distinguish analysis, classification, and drafting. Values are limited to 128 ASCII letters, digits, periods, underscores, colons, and hyphens. These labels do not change workspace, actor, or application attribution, which comes from the authenticated credential. Keep personal data, secrets, and prompt text out of these labels. The response ID and x-request-id identify the gateway run. Provider-reported tokens remain recorded when structured output validation fails. Monetary values use the configured model pricing, rather than provider invoices. The original output-token total includes reasoning tokens; pricing counts each reasoning token once, while retaining the breakdown for audit. Optional content-capture failures cannot overwrite settled usage. When a provider supplies no usage on failure, audit metadata marks it unavailable; known completed steps without a final total are marked provider_partial. Interrupted streams without final usage are labeled estimated_partial. Such records are not proof of zero provider spend and need provider-billing reconciliation for a complete accounting close. AI Studio run details show a warning for these incomplete records.

​
Native extensions

Tuturuuu-native response metadata reports billed workspace credits, provider cost when permitted, run and trace IDs, token or media units, and timing information. These fields extend the compatible response without changing the standard OpenAI fields. Text endpoints accept an optional bounded tool-loop extension:
max_steps must be between 1 and 8. The listed tools are deterministic, server-owned demonstration tools; arbitrary HTTP requests and code execution are not accepted. Non-streaming responses include tuturuuu.steps with only the ordered step number, type, name, status, and latency. Streaming responses emit the same sanitized trace in the final response.completed event before [DONE]. Workspace Studio dashboards combine settled ai_studio_runs with unmatched deductions from ai_credit_transactions. This includes ordinary workspace deductions and the signed-in member’s personal deductions when a free workspace uses a personal credit balance, without double-counting ledger rows linked to a Studio run. Billed credits and settled provider cost are shown separately; registered external-app runs therefore report provider cost while showing zero billed workspace credits. The usage and run-log responses include identifiers, model, feature, credential source, status, token or media units, settled credits and cost, and timing metadata. They never include raw prompts, model outputs, tool payloads, ledger metadata, or unsanitized provider errors. The legacy /api/ai/generate endpoint remains available as a compatibility adapter. New integrations should use the /v1 Studio endpoints.

​
Speech

POST /v1/audio/speech accepts input, optional voice, optional response_format (wav or pcm), and the google/gemini-3.1-flash-tts-preview model. The response is downloadable audio and is never cached. Google currently prices the model by text input tokens and audio output tokens; Tuturuuu records both provider cost and generated audio duration-derived token usage.

​
Retention and content capture

Metadata logging is enabled by default. Prompt, output, and tool content is captured only when the workspace enables content capture. Use the Studio retention controls to review the active policy before submitting sensitive data.

​
External provider costs

POST /v1/provider-costs imports one provider-reported USD run expense. Use a registered external-app session or an AI Studio key bound to that app, with X-Tuturuuu-Workspace-Id matching its workspace. Unbound keys cannot import costs. The existing ai:use app scope and registration checks apply. This endpoint does not execute AI, reserve credits, or debit the workspace.
Bodies are limited to 8 KiB. Workspace/app identity comes from authentication, never the body. Each workspace/app/provider/account/run has one record; newer observation timestamps can correct it and stale retries cannot overwrite it. A successful write returns { "accepted": true, "externalRunId": "run_123" }. Retry unavailable writes with the same run ID. Import provider totals only once: do not add event charges to an Apify usageTotalUsd total or import the same account invoice as additional run usage. The AI Studio Usage page has a Provider costs section using the selected date range, original run dates, and UTC months. Only imported records are included; unknown costs and expired runs are not zero-cost records. The workspace read API is GET /api/v1/workspaces/{wsId}/ai/provider-costs?from=...&to=..., authorized with use_ai_studio and a joined satellite session. Apply migration 20260906100000_external_provider_costs.sql before enabling import clients. During a schema-first rollout, unavailable storage returns 503 and the client must retain its pending records. The Supabase production migration remains an operator action. For an account exclusively dedicated to the sending app, import daily account usage with granularity: "account_day", accountId, a stable account/day externalRunId, and occurredAt at midnight UTC. These daily records replace covered run amounts in aggregates; run records remain for audit. Run imports may include accountId to distinguish multiple accounts. Never use account-day imports for a shared provider account without explicit attribution. Daily totals must reconcile with the provider’s post-discount billing-cycle total; do not silently allocate discounts or add current list-price surcharges. Apify’s reported usage includes applicable date-order/pay-per-event charges, storage and transfer. When IDs are only unique within a provider account, supply accountId on every record. Account-day totals include the complete UTC day whenever it overlaps the requested range; hourly costs cannot be inferred from a daily total.

​
External app usage reports

GET /v1/usage accepts an app-bound machine key or external-app session credential and X-Tuturuuu-Workspace-Id. It returns only AI metering attributed to the authenticated app in the matched workspace. Unbound keys and workspace mismatches receive 403. The response includes currency: "USD", source: "tuturuuu_ai_metering", workspaceId, appId, from, to, and daily rows: day, model, feature, executionMode, amountUsd, requests, failed, inputTokens, outputTokens, billedCredits, and unmeteredCredits. All retained app-attributed history is paginated in adjacent windows of at most 365 days. Reads neither debit credits nor create metering events. Reporting failures return 503, not a partial total. Combine amountUsd with provider-reported expenses without adding credit valuations again: credits are a separate accounting dimension of the same calls. These are recorded consumption costs, not proof of a paid invoice. Unconnected provider bills must remain explicit coverage gaps. Cache reports privately and keep machine credentials on the server. Validate with bun run --cwd apps/ai test src/app/v1/usage/route.test.ts.

​
Reviewed provider invoices

POST /v1/provider-invoices accepts an immutable, manually reviewed paid invoice snapshot. Use the same workspace-matched external-app credential as provider cost ingestion. Workspace, app and actor attribution come from the credential.
Success returns { "accepted": true, "reference": "example-invoice" }. Identical retries retain one receipt per workspace/app/provider/account/reference. Conflicting snapshots return 409; review the evidence rather than generating a new reference to bypass the conflict. Unknown fields, negative amounts, future reviews and reviews before issuance are rejected. Keep real invoice details and credentials in private configuration, never source control. AI Studio Integrations shows retained invoices separately from measured provider usage. Its workspace-authorized read API is GET /api/v1/workspaces/{wsId}/ai/provider-invoices and requires use_ai_studio. It paginates storage reads to avoid silently truncating all-time invoice totals. Invoice periods use issue dates; they do not establish consumption dates. Original amounts stay in USD and display conversion does not change the ledger. Do not add invoice and usage totals when they cover the same expenses. Neither invoice imports nor provider costs debit AI credits. Apply migration 20260907110000_external_provider_invoices.sql through the normal production migration workflow before enabling invoice delivery. This endpoint stores reviewed evidence; it does not fetch future provider invoices. A receipt’s sync time confirms persistence, not connection health or complete cost coverage.