{ "openapi": "3.1.0", "info": { "title": "NewEyes Open API", "description": "Changes within `/v1` are additive: new endpoints, optional fields and values. A set of values (event types, error codes, statuses and the like) may grow, so ignore any value you do not recognize. What ends a task never grows: a task ends with `task.completed`, `task.failed` or `task.stopped`.", "version": "1.0.0" }, "paths": { "/v1/users/{user_id}/tokens": { "post": { "tags": [ "tokens" ], "summary": "Issue user token", "description": "Issues a bearer token for one of the project's end users. Your backend calls this and hands the token to the user's app, which then calls the end-user operations (sessions, messages, files, voice) with it. `expires_in` sets its lifetime (60–86400 seconds, 3600 by default). A disabled user cannot be issued a token. Issuing a new token leaves the user's earlier ones working; revoke them to stop them.", "operationId": "issueUserToken", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project user to mint the token for.", "title": "User Id" }, "description": "Identifier of the project user to mint the token for." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TokenIssueIn" }, { "type": "null" } ], "title": "Req" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenIssueOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "permission_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.\n- `user_not_found` — The requested user was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_not_found": { "summary": "user_not_found", "value": { "error": { "type": "invalid_request_error", "code": "user_not_found", "message": "The requested user was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "delete": { "tags": [ "tokens" ], "summary": "Revoke user tokens", "description": "Revokes every token issued so far to one of the project's end users, e.g. when one may have leaked: each is refused from then on as an invalid token (`invalid_token`). Tokens issued afterwards work.", "operationId": "revokeUserTokens", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project user whose tokens to revoke.", "title": "User Id" }, "description": "Identifier of the project user whose tokens to revoke." } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.\n- `user_not_found` — The requested user was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_not_found": { "summary": "user_not_found", "value": { "error": { "type": "invalid_request_error", "code": "user_not_found", "message": "The requested user was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/me": { "get": { "tags": [ "users" ], "summary": "Get me", "description": "Returns the end user the presented token belongs to, with their project. Only a user token is accepted here; a project key is refused.", "operationId": "getMe", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/users": { "post": { "tags": [ "users" ], "summary": "Create user", "description": "Creates one of the project's end users and returns its `id`. Keep that id with your own record of the user: every call creates a new user. Send `issue_token: true` to get the user's first token in the same answer.", "operationId": "createUser", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/UserCreateIn" }, { "type": "null" } ], "title": "Req" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreatedOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "get": { "tags": [ "users" ], "summary": "List users", "description": "Lists the project's end users, oldest first. Deleted users are not included.", "operationId": "listUsers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of users to return in one page.", "default": 20, "title": "Limit" }, "description": "Maximum number of users to return in one page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOut_UserOut_" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/users/{user_id}": { "get": { "tags": [ "users" ], "summary": "Get user", "description": "Returns one of the project's end users.", "operationId": "getUser", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project user to retrieve.", "title": "User Id" }, "description": "Identifier of the project user to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.\n- `user_not_found` — The requested user was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_not_found": { "summary": "user_not_found", "value": { "error": { "type": "invalid_request_error", "code": "user_not_found", "message": "The requested user was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "patch": { "tags": [ "users" ], "summary": "Enable or disable user", "description": "Disables or re-enables an end user. Disabling revokes every token the user holds, and no new token can be issued while disabled; after re-enabling, issue the user a new token.", "operationId": "updateUser", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project user to update.", "title": "User Id" }, "description": "Identifier of the project user to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPatchIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.\n- `user_not_found` — The requested user was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_not_found": { "summary": "user_not_found", "value": { "error": { "type": "invalid_request_error", "code": "user_not_found", "message": "The requested user was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "delete": { "tags": [ "users" ], "summary": "Delete user", "description": "Deletes an end user: their tokens stop working and they no longer appear in lists or reads.", "operationId": "deleteUser", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project user to delete.", "title": "User Id" }, "description": "Identifier of the project user to delete." } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.\n- `invalid_secret` — The API secret is invalid.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "invalid_secret": { "summary": "invalid_secret", "value": { "error": { "type": "authentication_error", "code": "invalid_secret", "message": "The API secret is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.\n- `project_disabled` — This project is not active.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "permission_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `project_not_found` — The requested project was not found.\n- `user_not_found` — The requested user was not found.", "content": { "application/json": { "examples": { "project_not_found": { "summary": "project_not_found", "value": { "error": { "type": "invalid_request_error", "code": "project_not_found", "message": "The requested project was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_not_found": { "summary": "user_not_found", "value": { "error": { "type": "invalid_request_error", "code": "user_not_found", "message": "The requested user was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/files": { "post": { "tags": [ "files" ], "summary": "Create file", "description": "Upload an image, a video or an audio clip (MP3, WAV, M4A or AAC) in one step:\nPOST its bytes as `multipart/form-data` (the `file` field). The server sniffs the\nreal type from the bytes (not the declared content-type), enforces the per-type\nsize ceiling, stores it, and returns the stored file — attach an image or a video\nto a message later by its `id`, or pass any of them to a generation as input. The\nfile expires at its `expires_at` unless it is sent in a message or used by a\ngeneration first.", "operationId": "createFile", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_createFile" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `file_too_large` — The file exceeds the maximum allowed size.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "file_too_large": { "summary": "file_too_large", "value": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "The file exceeds the maximum allowed size.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `unsupported_media_type` — The media type is not supported.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "unsupported_media_type": { "summary": "unsupported_media_type", "value": { "error": { "type": "invalid_request_error", "code": "unsupported_media_type", "message": "The media type is not supported.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/files/{file_id}": { "get": { "tags": [ "files" ], "summary": "Get file", "description": "Returns a file the calling end user uploaded or generated: its name, size and type, and a freshly signed `download_url` for its content. An expired file is `404` `file_expired`.", "operationId": "getFile", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of a file created with POST /v1/files or produced by a generation.", "title": "File Id" }, "description": "Identifier of a file created with POST /v1/files or produced by a generation." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/sessions": { "post": { "tags": [ "sessions" ], "summary": "Create session", "description": "Creates a conversation session for the calling end user. `output_format` fixes the reply form for the session's life, and `capabilities` or `exclude_capabilities` what the assistant may use in it (every capability when neither is sent). Include `text` (and optionally `attachments`, as in a later message) to start the first task right away: the response then carries its `task_id`, its reply streams on `GET /v1/sessions/{session_id}/events` — open it with `Last-Event-ID` set to the returned `last_event_id` to receive the task from its first frame — and is kept in the session's message list. Starting a task needs a spendable balance on the project's billing account; creating an empty session does not.", "operationId": "createSession", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the session again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the session again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreateIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreatedOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `file_too_large` — The file exceeds the maximum allowed size.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "The file exceeds the maximum allowed size.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `unsupported_media_type` — The media type is not supported.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "unsupported_media_type": { "summary": "unsupported_media_type", "value": { "error": { "type": "invalid_request_error", "code": "unsupported_media_type", "message": "The media type is not supported.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "get": { "tags": [ "sessions" ], "summary": "List sessions", "description": "Lists the calling end user's sessions, newest first. Deleted sessions are not included.", "operationId": "listSessions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of sessions to return in one page.", "default": 50, "title": "Limit" }, "description": "Maximum number of sessions to return in one page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOut_SessionOut_" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/sessions/{session_id}": { "get": { "tags": [ "sessions" ], "summary": "Get session", "description": "Returns one of the calling end user's sessions.", "operationId": "getSession", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session to retrieve.", "title": "Session Id" }, "description": "Identifier of the session to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "delete": { "tags": [ "sessions" ], "summary": "Delete session", "description": "Deletes one of the calling end user's sessions; it no longer appears in lists or reads. A voice session cannot be deleted while its call is still connected. If cleaning up the session's stored data fails, nothing is deleted (`503`); retry the request.", "operationId": "deleteSession", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session to delete.", "title": "Session Id" }, "description": "Identifier of the session to delete." } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `call_in_progress` — A live call is using this session; end the call before deleting it.", "content": { "application/json": { "examples": { "call_in_progress": { "summary": "call_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "call_in_progress", "message": "A live call is using this session; end the call before deleting it.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "503": { "description": "The service is temporarily unavailable; retry after a short delay.\n- `service_unavailable` — The service is temporarily unavailable. Please retry shortly.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please retry shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/sessions/{session_id}/stop": { "post": { "tags": [ "sessions" ], "summary": "Stop running task", "description": "Stops the session's running task, if any; the task then ends with a `task.stopped` event on the session's event stream. Returns that task's `task_id`, or `null` when no task was running.", "operationId": "stopSessionTask", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session to stop.", "title": "Session Id" }, "description": "Identifier of the session to stop." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRefOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/sessions/{session_id}/events": { "get": { "tags": [ "sessions" ], "summary": "Stream session events", "description": "Follows the session as server-sent events. Every frame carries its `task_id`. A task sends `task.started`; `text.delta` frames with its reply text while it is written; `task.progress` for each step under way (a `category` — `search`, `image`, `video`, `music`, `memory`, `analysis`, `other` — and a short `text`); `media.updated` when an image, video, audio or file it produces changes `status` (`running`, `completed`, `failed`, `canceled`; a completed one carries an `attachment` whose link expires, a failed one an `error`); in an `a2ui` session, `ui.updated` with its whole UI data whenever that changes; `suggestions` with up to 3 messages the user might send next; then one `task.completed`, `task.stopped` or `task.failed` frame ends it, whose `text` is the whole reply. A generated asset may still be reported after its task ended. Every frame has its own `id`. To follow a task you started, send the `last_event_id` its request returned as `Last-Event-ID`: the stream sends the task from its first frame (`0` sends the session from its start). Without `Last-Event-ID` the stream starts from now — earlier replies are read from the message list. A connection lasts at most 10 minutes; reconnect with `Last-Event-ID` set to the last frame's `id` to continue right after it. While there is nothing to send, a `: ping` comment comes every 15 seconds: after 45 seconds with nothing at all, treat the connection as dropped and reconnect. A user keeps at most 16 streams open at once, at most 4 on one session — opening another ends the oldest, on that session first, otherwise the user's oldest. A new stream is refused only while every stream the user holds was opened in the last 10 seconds.", "operationId": "streamSessionEvents", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session to follow.", "title": "Session Id" }, "description": "Identifier of the session to follow." }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "The `id` of the last frame received, to resume right after it; a task's `last_event_id`, to receive the task from its first frame; or `0` for the session from its start.", "title": "Last-Event-Id" }, "description": "The `id` of the last frame received, to resume right after it; a task's `last_event_id`, to receive the task from its first frame; or `0` for the session from its start." } ], "responses": { "200": { "description": "Server-sent events. In an `a2ui` session the end frame of a completed or stopped task also carries the UI data (`ui`).", "content": { "text/event-stream": {} } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many event streams opened at once for this user. Retry in a few seconds.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many event streams opened at once for this user. Retry in a few seconds.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "503": { "description": "The service is temporarily unavailable; retry after a short delay.\n- `service_unavailable` — Live updates are at capacity right now. Please retry shortly.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Live updates are at capacity right now. Please retry shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/sessions/{session_id}/brief": { "get": { "tags": [ "brief" ], "summary": "Get session brief", "description": "Retrieve the session's brief (topics, action items, speakers, visuals). Only a\nvoice session gets one: it is built automatically when the call ends, reads\n``running`` while it builds, and ``none`` for a session without one. A call\nbelow the minimum length returns ``transcript_only`` rather than an error.", "operationId": "getSessionBrief", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session whose brief to return.", "title": "Session Id" }, "description": "Identifier of the session whose brief to return." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/sessions/{session_id}/messages": { "post": { "tags": [ "messages" ], "summary": "Send message", "description": "Sends the end user's next message and starts a task that answers it. One task runs at a time per session: while a task is still running, a new message is refused with `session_busy` — wait for the task's end event, or stop it first. The reply is kept in the message list and streams on `GET /v1/sessions/{session_id}/events`: open it with `Last-Event-ID` set to the returned `last_event_id` to receive the task from its first frame. Or set `stream: true` to receive the task on this request: the response is then `200` with the task's own frames, as the event stream sends them, ending with its end frame — or, like any event stream, after 10 minutes (a refused message still answers with its error); an asset still being made when the task ends is reported later on the event stream. A response that ends without the end frame — dropped, or at its time limit — does not stop the task: continue on the event stream with the last frame's `id`, or retry with the same `Idempotency-Key` to receive the same task again from its first frame. Needs a spendable balance on the project's billing account. A voice session does not take text messages. A message the user sends by acting on an `a2ui` surface carries the renderer's action in `a2ui_action`.", "operationId": "sendMessage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session to send to.", "title": "Session Id" }, "description": "Identifier of the session to send to." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the task again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the task again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageIn" } } } }, "responses": { "200": { "description": "With `stream: true`: the task's frames as server-sent events, from its first frame through its end frame.", "content": { "text/event-stream": {} } }, "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStartedOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `session_busy` — This session is already running a task; wait for it to finish before starting another.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.\n- `session_not_taskable` — This session does not accept tasks.", "content": { "application/json": { "examples": { "session_busy": { "summary": "session_busy", "value": { "error": { "type": "invalid_request_error", "code": "session_busy", "message": "This session is already running a task; wait for it to finish before starting another.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "session_not_taskable": { "summary": "session_not_taskable", "value": { "error": { "type": "invalid_request_error", "code": "session_not_taskable", "message": "This session does not accept tasks.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `file_too_large` — The file exceeds the maximum allowed size.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "The file exceeds the maximum allowed size.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `unsupported_media_type` — The media type is not supported.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "unsupported_media_type": { "summary": "unsupported_media_type", "value": { "error": { "type": "invalid_request_error", "code": "unsupported_media_type", "message": "The media type is not supported.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "503": { "description": "The service is temporarily unavailable; retry after a short delay.\n- `service_unavailable` — Live updates are at capacity right now. Please retry shortly.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Live updates are at capacity right now. Please retry shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "get": { "tags": [ "messages" ], "summary": "List session messages", "description": "Lists the conversation of one of the calling end user's sessions in order: the user's messages, the assistant's replies with their media, and error notices; `verbose=true` adds activity items. Each reply carries the `task_id` of the task that wrote it. A voice session lists its transcript. Page with `next_cursor`: a cursor keeps its place even after the session's older messages are archived. Archiving can change a message's `id`, so match replies by `task_id`.", "operationId": "listMessages", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the session whose messages to return.", "title": "Session Id" }, "description": "Identifier of the session whose messages to return." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of messages to return in one page.", "default": 50, "title": "Limit" }, "description": "Maximum number of messages to return in one page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page." }, { "name": "verbose", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, also include activity items (intermediate tool and step events) alongside the conversation messages.", "default": false, "title": "Verbose" }, "description": "When true, also include activity items (intermediate tool and step events) alongside the conversation messages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOut_MessageOut_" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/audio/transcriptions": { "post": { "tags": [ "audio" ], "summary": "Transcribe audio", "description": "Transcribes a short audio clip to text. Send the clip as multipart form data (`file`, an `audio/*` type, up to 25 MB); `language` is an optional hint. Needs a spendable balance on the project's billing account.", "operationId": "createTranscription", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_createTranscription" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.\n- `permission_denied` — You do not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "permission_denied": { "summary": "permission_denied", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `file_too_large` — The file exceeds the maximum allowed size.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "file_too_large": { "summary": "file_too_large", "value": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "The file exceeds the maximum allowed size.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `unsupported_media_type` — The media type is not supported.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "unsupported_media_type": { "summary": "unsupported_media_type", "value": { "error": { "type": "invalid_request_error", "code": "unsupported_media_type", "message": "The media type is not supported.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "502": { "description": "An upstream service returned an error while handling the request.\n- `upstream_error` — Transcription failed. Please try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "upstream_error": { "summary": "upstream_error", "value": { "error": { "type": "api_error", "code": "upstream_error", "message": "Transcription failed. Please try again.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "503": { "description": "The service is temporarily unavailable; retry after a short delay.\n- `service_unavailable` — Transcription is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Transcription is temporarily unavailable.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/images/generations": { "post": { "tags": [ "images" ], "summary": "Generate an image", "description": "Draws one image from a description, optionally after reference images. Answers `202` with the queued generation; poll `GET /v1/images/{image_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "generateImage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/images/edits": { "post": { "tags": [ "images" ], "summary": "Edit an image", "description": "Edits or combines the end user's images as described, keeping what the description does not change. Answers `202` with the queued generation; poll `GET /v1/images/{image_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "editImage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageEditIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/images": { "get": { "tags": [ "images" ], "summary": "List image generations", "description": "Lists the calling end user's image generations, newest first.", "operationId": "listImages", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of image generations to return in one page.", "default": 50, "title": "Limit" }, "description": "Maximum number of image generations to return in one page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOut_ImageOut_" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/images/{image_id}": { "get": { "tags": [ "images" ], "summary": "Get an image generation", "description": "Returns one of the calling end user's image generations; once `completed`, its `files` carry the image with a fresh download link.", "operationId": "getImage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of an image generation.", "title": "Image Id" }, "description": "Identifier of an image generation." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `generation_not_found` — The requested generation was not found.", "content": { "application/json": { "examples": { "generation_not_found": { "summary": "generation_not_found", "value": { "error": { "type": "invalid_request_error", "code": "generation_not_found", "message": "The requested generation was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos": { "post": { "tags": [ "videos" ], "summary": "Generate a video", "description": "Makes one video from a description — optionally from a first (and last) frame, or at `pro` quality after reference images, videos and audio. Answers `202` with the queued generation; poll `GET /v1/videos/{video_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "generateVideo", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `insufficient_available_credits` — Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "insufficient_available_credits": { "summary": "insufficient_available_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_available_credits", "message": "Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "get": { "tags": [ "videos" ], "summary": "List video generations", "description": "Lists the calling end user's video generations, newest first.", "operationId": "listVideos", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of video generations to return in one page.", "default": 50, "title": "Limit" }, "description": "Maximum number of video generations to return in one page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOut_VideoOut_" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/edits": { "post": { "tags": [ "videos" ], "summary": "Edit a video", "description": "Changes part of a video as described — swaps an object, restyles it, adds something — keeping its length and its shots. Answers `202` with the queued generation; poll `GET /v1/videos/{video_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "editVideo", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoEditIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `insufficient_available_credits` — Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "insufficient_available_credits": { "summary": "insufficient_available_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_available_credits", "message": "Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/remakes": { "post": { "tags": [ "videos" ], "summary": "Remake a video", "description": "Shoots a new take of the described scene after a video. Answers `202` with the queued generation; poll `GET /v1/videos/{video_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "remakeVideo", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoRemakeIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `insufficient_available_credits` — Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "insufficient_available_credits": { "summary": "insufficient_available_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_available_credits", "message": "Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/motion-transfers": { "post": { "tags": [ "videos" ], "summary": "Transfer motion to an image", "description": "Animates the person in an image so they move the way the person in a video does. Answers `202` with the queued generation; poll `GET /v1/videos/{video_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "transferMotion", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotionTransferIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `insufficient_available_credits` — Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "insufficient_available_credits": { "summary": "insufficient_available_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_available_credits", "message": "Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/reframes": { "post": { "tags": [ "videos" ], "summary": "Reframe a video", "description": "Changes only a video's frame shape and resolution, extending the picture to fill the new frame; the content stays the same. Answers `202` with the queued generation; poll `GET /v1/videos/{video_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "reframeVideo", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoReframeIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `insufficient_available_credits` — Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "insufficient_available_credits": { "summary": "insufficient_available_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_available_credits", "message": "Too little of the billing account's balance is free for this request: the rest is held by its generations still in progress. Wait for them to finish, or top up.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/soundtracks": { "post": { "tags": [ "videos" ], "summary": "Replace a video's soundtrack", "description": "Lays an audio clip over a video in place of its own sound (trimmed, with a fade, when the clip is longer). Answers `202` with the queued generation; poll `GET /v1/videos/{video_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "replaceSoundtrack", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoundtrackIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `file_not_found` — The requested file was not found.\n- `file_expired` — The requested file has expired.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "The requested file was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "file_expired": { "summary": "file_expired", "value": { "error": { "type": "invalid_request_error", "code": "file_expired", "message": "The requested file has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/{video_id}": { "get": { "tags": [ "videos" ], "summary": "Get a video generation", "description": "Returns one of the calling end user's video generations; once `completed`, its `files` carry the video with a fresh download link.", "operationId": "getVideo", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of a video generation.", "title": "Video Id" }, "description": "Identifier of a video generation." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `generation_not_found` — The requested generation was not found.", "content": { "application/json": { "examples": { "generation_not_found": { "summary": "generation_not_found", "value": { "error": { "type": "invalid_request_error", "code": "generation_not_found", "message": "The requested generation was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/videos/{video_id}/cancel": { "post": { "tags": [ "videos" ], "summary": "Cancel a video generation", "description": "Cancels a video generation. A queued one ends `canceled` at once. One already rendering is asked to stop and stays `running` until that is settled: it ends `canceled`, or `completed` — delivered and charged as usual — when the video was finished first. A generation that has ended is returned unchanged.", "operationId": "cancelVideo", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of a video generation.", "title": "Video Id" }, "description": "Identifier of a video generation." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `generation_not_found` — The requested generation was not found.", "content": { "application/json": { "examples": { "generation_not_found": { "summary": "generation_not_found", "value": { "error": { "type": "invalid_request_error", "code": "generation_not_found", "message": "The requested generation was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/music": { "post": { "tags": [ "music" ], "summary": "Generate music", "description": "Makes one song (an MP3 file) as described. Answers `202` with the queued generation; poll `GET /v1/music/{music_id}` until it has `completed` (its `files` then hold the result) or `failed`. Starting one needs a spendable balance on the project's billing account, and an end user may have 3 generations unfinished at a time.", "operationId": "generateMusic", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, { "type": "null" } ], "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours.", "title": "Idempotency-Key" }, "description": "Optional. Retrying the same request with the same key returns the first answer instead of starting the generation again; keys are kept for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicCreateIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `idempotency_conflict` — This Idempotency-Key belongs to a different request.\n- `idempotency_in_progress` — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "content": { "application/json": { "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "This Idempotency-Key belongs to a different request.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_in_progress", "message": "The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } }, "get": { "tags": [ "music" ], "summary": "List music generations", "description": "Lists the calling end user's music generations, newest first.", "operationId": "listMusic", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of music generations to return in one page.", "default": 50, "title": "Limit" }, "description": "Maximum number of music generations to return in one page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor copied from a previous response's `next_cursor`. Omit to start from the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOut_MusicOut_" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/music/{music_id}": { "get": { "tags": [ "music" ], "summary": "Get a music generation", "description": "Returns one of the calling end user's music generations; once `completed`, its `files` carry the song with a fresh download link.", "operationId": "getMusic", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "music_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of a music generation.", "title": "Music Id" }, "description": "Identifier of a music generation." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `generation_not_found` — The requested generation was not found.", "content": { "application/json": { "examples": { "generation_not_found": { "summary": "generation_not_found", "value": { "error": { "type": "invalid_request_error", "code": "generation_not_found", "message": "The requested generation was not found.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } }, "/v1/realtime/sessions": { "post": { "tags": [ "realtime" ], "summary": "Create realtime session", "description": "Start a voice session for the calling end user — or, with\n`session_id`, rejoin one of theirs that has not ended — and return its `id` with a\nshort-lived `client_secret`.\n\nOpen a WebSocket to `websocket_url` before `client_secret.expires_at`, with the secret in\nthe `Authorization: Bearer` header. A browser, which cannot set that header, offers two\nsubprotocols instead: `neweyes-realtime` and `neweyes-secret.` followed by\nthe secret. A secret opens one connection.\n\nThe voice session is a session like any other: read it, its transcript and its brief\nthrough `/v1/sessions`. A closed connection does not end it: to go on with the call,\ncreate a realtime session with its `session_id` for a fresh secret and connect again —\nthe conversation picks up where it left off. One connection holds a session at a time;\na newer one takes it over. End the session with `POST\n/v1/realtime/sessions/{session_id}/end`. One left without a connection ends by itself,\nthough never sooner than 10 minutes after its last connection\nclosed — a time that may grow but will not shrink. A rejoin after that is refused with\n`session_ended`: start a new session. Its brief is built once it ends.\n\nThe voice assistant may call two tools, delivered as `tool_call` frames for your\nclient to run and answer with a `tool_result`:\n\n- `create_task` — send its `task` text as a message to a text session (`POST\n /v1/sessions`, or `POST /v1/sessions/{session_id}/messages` on one you keep for\n the call) and answer with the returned `task_id`. The task's progress and\n reply arrive on `GET /v1/sessions/{session_id}/events`.\n- `get_task_status` — answer with what that event stream has shown for the task:\n still running, or its end (completed with its reply, stopped, or failed).\n\nA new voice session opens the capabilities you choose with `capabilities` or\n`exclude_capabilities`, as a text session does, and keeps them for its life; a rejoin\nkeeps them too, so it sends neither field. The voice assistant is told what the session\nleft out, so it does not offer or delegate it — but the text session a task runs in is\nyours to create, and the call's choice does not carry over to it: create it with the\nsame `capabilities` or `exclude_capabilities`, or it opens every capability. A call\nwhose capabilities cannot be read does not start: it closes with\n`1011`.\n\nA frame your client sends is dropped, with no reply, when it is over 4 MiB, when\nits audio or image `data` is not base64, when an `input_text` is over 32,000\ncharacters or holds a NUL character, or when a `tool_result`'s `output` is over\n32,000 characters as JSON.\n\nThe socket has no request/response body, so its outcome is reported by the\nWebSocket **close code**:\n\n- `1000` — normal closure, or the session was ended.\n- `1001` — going away; one side is ending the session (may be relayed\n when the underlying session terminates).\n- `1011` — a server-side error, or the voice service is temporarily\n unavailable; retry later. A close from the voice service with a code not listed here\n arrives as this one.\n- `1012` — the server is restarting for a planned redeploy; reconnect\n shortly.\n- `4001` — the secret is missing, invalid, expired or already used,\n its session was deleted or has ended, or the caller's access was revoked; get a fresh\n secret (with the same `session_id`, while the session has not ended).\n- `4009` — a newer connection took the session over; do not reconnect from\n this one, or the two take it from each other in turn.\n- `4401` — authentication failed, or the account is not active.\n- `4429` — the billing account is out of credits, or too many voice\n sessions are already active; top up or close one, then retry.", "operationId": "createRealtimeSession", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RealtimeSessionIn" }, { "type": "null" } ], "title": "Req" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeSessionOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `session_not_realtime` — This session is not a voice session.\n- `session_ended` — This voice session has ended; start a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "session_not_realtime": { "summary": "session_not_realtime", "value": { "error": { "type": "invalid_request_error", "code": "session_not_realtime", "message": "This session is not a voice session.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "session_ended": { "summary": "session_ended", "value": { "error": { "type": "invalid_request_error", "code": "session_ended", "message": "This voice session has ended; start a new one.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "413": { "description": "The request body is larger than the allowed limit.\n- `payload_too_large` — The request body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `insufficient_credits` — The billing account has insufficient credits.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": { "type": "rate_limit_error", "code": "insufficient_credits", "message": "The billing account has insufficient credits.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" }, "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/realtime/sessions/{session_id}/end": { "post": { "tags": [ "realtime" ], "summary": "End a realtime session", "description": "Ends one of the caller's voice sessions: a connection holding it closes (`1000`) and its brief is built; the session stays readable. Ending a session that has already ended returns it unchanged.", "operationId": "endRealtimeSession", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Identifier of the voice session to end.", "title": "Session Id" }, "description": "Identifier of the voice session to end." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionOut" } } } }, "401": { "description": "Authentication failed: the credential is missing, malformed, expired, or revoked.\n- `invalid_token` — The access token is invalid.\n- `project_disabled` — This project is not active.\n- `token_expired` — The access token has expired.\n- `user_disabled` — This user is not active.", "content": { "application/json": { "examples": { "invalid_token": { "summary": "invalid_token", "value": { "error": { "type": "authentication_error", "code": "invalid_token", "message": "The access token is invalid.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "project_disabled": { "summary": "project_disabled", "value": { "error": { "type": "authentication_error", "code": "project_disabled", "message": "This project is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "token_expired": { "summary": "token_expired", "value": { "error": { "type": "authentication_error", "code": "token_expired", "message": "The access token has expired.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } }, "user_disabled": { "summary": "user_disabled", "value": { "error": { "type": "authentication_error", "code": "user_disabled", "message": "This user is not active.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "404": { "description": "The requested resource does not exist, or is not visible to the caller.\n- `session_not_found` — Session not found", "content": { "application/json": { "examples": { "session_not_found": { "summary": "session_not_found", "value": { "error": { "type": "invalid_request_error", "code": "session_not_found", "message": "Session not found", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n- `session_not_realtime` — This session is not a voice session.", "content": { "application/json": { "examples": { "session_not_realtime": { "summary": "session_not_realtime", "value": { "error": { "type": "invalid_request_error", "code": "session_not_realtime", "message": "This session is not a voice session.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "422": { "description": "A request value failed validation; the details array names each offending field.\n- `validation_failed` — The request payload failed validation.", "content": { "application/json": { "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request payload failed validation.", "param": "session_id", "details": [ { "param": "session_id", "message": "Input should be a valid UUID" } ], "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "429": { "description": "Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.\n- `rate_limited` — Too many requests. Please slow down.", "content": { "application/json": { "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } }, "500": { "description": "An unexpected server-side error occurred.\n- `internal` — An unexpected error occurred.", "content": { "application/json": { "examples": { "internal": { "summary": "internal", "value": { "error": { "type": "api_error", "code": "internal", "message": "An unexpected error occurred.", "request_id": "8b1c2e0f4d3a4c5e9f6a7b8c9d0e1f2a" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelopeOut" } } } } } } } }, "components": { "schemas": { "A2uiActionBodyIn": { "properties": { "name": { "type": "string", "maxLength": 64, "pattern": "^[^\\x00-\\x1f\\x7f\\u0085\\u2028\\u2029]+$", "title": "Name", "description": "The `name` of the component's `action.event`." }, "surfaceId": { "type": "string", "maxLength": 200, "pattern": "^[^\\x00-\\x1f\\x7f\\u0085\\u2028\\u2029]+$", "title": "Surfaceid", "description": "The `surfaceId` of the surface the component is on." }, "sourceComponentId": { "type": "string", "maxLength": 200, "pattern": "^[^\\x00-\\x1f\\x7f\\u0085\\u2028\\u2029]+$", "title": "Sourcecomponentid", "description": "The `id` of the component the user acted on." }, "timestamp": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Timestamp", "description": "When the user acted (ISO 8601), as the renderer reports it." }, "context": { "type": "object", "title": "Context", "description": "The `context` of the component's `action.event` with its data bindings resolved: the values the user picked or entered. At most 4000 characters as JSON, nested at most 8 levels deep." }, "userMessage": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Usermessage", "description": "The component's `action.event.userMessage`. Taken and not used: `text` is what the user said." }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Client-side metadata the renderer attaches. Taken and not used; bounded like `context`." } }, "type": "object", "required": [ "name", "surfaceId", "sourceComponentId" ], "title": "A2uiActionBodyIn", "description": "What the user did on an `a2ui` surface, as the renderer reports it." }, "A2uiActionIn": { "properties": { "version": { "type": "string", "const": "v1.0", "title": "Version", "description": "The a2ui protocol version: `v1.0`." }, "action": { "$ref": "#/components/schemas/A2uiActionBodyIn" } }, "additionalProperties": false, "type": "object", "required": [ "version", "action" ], "title": "A2uiActionIn", "description": "A UI action from an `a2ui` surface: the renderer's a2ui `action` message, as is." }, "AttachmentIn": { "properties": { "file_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "File Id", "description": "Identifier of an owned file created via POST /v1/files. Provide exactly one of `file_id` or `file_data`." }, "file_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Data", "description": "Base64-encoded file bytes (a `data:…;base64,` prefix is accepted and ignored). Provide exactly one of `file_id` or `file_data`." } }, "additionalProperties": false, "type": "object", "title": "AttachmentIn", "description": "One message attachment: exactly one of an owned ``file_id`` or inline base64\n``file_data``." }, "Body_createFile": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "The file to upload (an image, a video or an audio clip)." } }, "type": "object", "required": [ "file" ], "title": "Body_createFile" }, "Body_createTranscription": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "The audio clip to transcribe, sent as multipart form data." }, "language": { "anyOf": [ { "type": "string", "maxLength": 35, "pattern": "^(?:[Aa][Uu][Tt][Oo]|[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8})*)$" }, { "type": "null" } ], "title": "Language", "description": "Optional hint for the spoken language: a language code (for example, `en`); a regional tag such as `en-US` counts as its language. `auto`, or no value, has the language inferred from the audio." } }, "type": "object", "required": [ "file" ], "title": "Body_createTranscription" }, "BriefActionItemOut": { "properties": { "task": { "type": "string", "title": "Task" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "due": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, "type": "object", "required": [ "task" ], "title": "BriefActionItemOut" }, "BriefOut": { "properties": { "object": { "type": "string", "const": "brief", "title": "Object", "default": "brief" }, "session_id": { "type": "string", "title": "Session Id" }, "status": { "type": "string", "enum": [ "none", "running", "completed", "transcript_only", "failed" ], "title": "Status" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "topics": { "items": { "$ref": "#/components/schemas/BriefTopicOut" }, "type": "array", "title": "Topics" }, "action_items": { "items": { "$ref": "#/components/schemas/BriefActionItemOut" }, "type": "array", "title": "Action Items" }, "speakers": { "items": { "type": "string" }, "type": "array", "title": "Speakers" }, "visuals": { "items": { "$ref": "#/components/schemas/BriefVisualOut" }, "type": "array", "title": "Visuals" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "session_id", "status" ], "title": "BriefOut" }, "BriefTopicOut": { "properties": { "title": { "type": "string", "title": "Title" }, "conclusion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conclusion" }, "details": { "items": { "type": "string" }, "type": "array", "title": "Details" }, "actions": { "items": { "type": "string" }, "type": "array", "title": "Actions" }, "open_questions": { "items": { "type": "string" }, "type": "array", "title": "Open Questions" } }, "type": "object", "required": [ "title" ], "title": "BriefTopicOut" }, "BriefVisualOut": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caption" }, "captured_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Captured At" }, "topic_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic Title" } }, "type": "object", "title": "BriefVisualOut" }, "ClientSecretOut": { "properties": { "value": { "type": "string", "title": "Value", "description": "The secret: send it when opening `websocket_url`; it opens one connection." }, "expires_at": { "type": "integer", "title": "Expires At", "description": "Unix seconds after which the secret is rejected." } }, "type": "object", "required": [ "value", "expires_at" ], "title": "ClientSecretOut", "description": "The short-lived secret that lets the client open the voice stream." }, "ErrorBodyOut": { "properties": { "type": { "type": "string", "enum": [ "api_error", "authentication_error", "invalid_request_error", "permission_error", "rate_limit_error" ], "title": "Type", "description": "Error family derived from the HTTP status. Always present." }, "code": { "type": "string", "title": "Code", "description": "Stable machine-readable code a client branches on. Always present.\n\nA stable, machine-readable error code the client can branch on (distinct from the human ``message``). New codes may be added over time, so treat an unknown code as its HTTP-status family. Codes by status:\n- 400: bad_request\n- 401: invalid_secret, invalid_token, project_disabled, token_expired, user_disabled\n- 403: permission_denied, project_disabled, user_disabled\n- 404: file_expired, file_not_found, generation_not_found, not_found, project_not_found, session_not_found, user_not_found\n- 405: method_not_allowed\n- 409: call_in_progress, conflict, idempotency_conflict, idempotency_in_progress, session_busy, session_ended, session_not_realtime, session_not_taskable\n- 413: file_too_large, payload_too_large\n- 422: unsupported_media_type, validation_failed\n- 429: insufficient_available_credits, insufficient_credits, rate_limited\n- 500: internal\n- 502: upstream_error\n- 503: service_unavailable" }, "message": { "type": "string", "title": "Message", "description": "Human-readable English summary for display or logging; never branch on it. Always present." }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param", "description": "Name of the request field the failure is attributed to, when there is one: always on validation errors (422), and on other errors about a single field (for example a file not found, or a file too large)." }, "details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ErrorDetailOut" }, "type": "array" }, { "type": "null" } ], "title": "Details", "description": "One entry per offending request field. Present only on validation errors (422)." }, "request_id": { "type": "string", "title": "Request Id", "description": "Correlates the response with server logs; also sent as the `X-Request-Id` header. Always present." } }, "additionalProperties": false, "type": "object", "required": [ "type", "code", "message", "request_id" ], "title": "ErrorBodyOut", "description": "The ``error`` object every failure returns." }, "ErrorDetailOut": { "properties": { "param": { "type": "string", "title": "Param", "description": "Dotted path of the offending request field, e.g. `attachments[0].file_id`." }, "message": { "type": "string", "title": "Message", "description": "What was wrong with that field." } }, "additionalProperties": false, "type": "object", "required": [ "param", "message" ], "title": "ErrorDetailOut", "description": "One field-level problem inside a validation error's ``details`` array." }, "ErrorEnvelopeOut": { "properties": { "error": { "$ref": "#/components/schemas/ErrorBodyOut" } }, "additionalProperties": false, "type": "object", "required": [ "error" ], "title": "ErrorEnvelopeOut", "description": "The top-level error response body: ``{\"error\": {...}}``." }, "FileOut": { "properties": { "object": { "type": "string", "const": "file", "title": "Object", "default": "file" }, "id": { "type": "string", "title": "Id" }, "filename": { "type": "string", "title": "Filename" }, "size": { "type": "integer", "title": "Size" }, "content_type": { "type": "string", "title": "Content Type" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url", "description": "A link to download the file's content, signed afresh on every read and valid for 60 minutes (until `download_url_expires_at`). Fetch the file again for a new link. `null` when a link cannot be made right now." }, "download_url_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Download Url Expires At", "description": "When `download_url` stops working." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "When the file expires: from then on it can no longer be read or used, and its content is deleted. `null` when it never expires — a file sent in a message is kept with that conversation, a file a generation uses is kept, and a generation's output is kept. An uploaded file expires 30 days after its upload unless it is sent in a message or used by a generation first." } }, "type": "object", "required": [ "id", "filename", "size", "content_type", "created_at" ], "title": "FileOut" }, "GenerationErrorOut": { "properties": { "code": { "type": "string", "enum": [ "content_blocked", "insufficient_credits", "insufficient_available_credits", "invalid_input", "generation_failed", "timeout" ], "title": "Code", "description": "Why the generation failed: `content_blocked` (a content safety check refused the request or an input), `insufficient_credits` (the billing account ran out), `invalid_input` (an input could not be used), `generation_failed` (it did not produce a result) or `timeout` (it did not finish in time)." }, "message": { "type": "string", "title": "Message", "description": "A human-readable explanation." } }, "type": "object", "required": [ "code", "message" ], "title": "GenerationErrorOut" }, "ImageEditIn": { "properties": { "prompt": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Prompt", "description": "The change to make, referring to the images by position (\"the first image\"); everything not mentioned stays as it is." }, "images": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 8, "minItems": 1, "title": "Images", "description": "1 to 8 images (file ids) to edit or combine." } }, "additionalProperties": false, "type": "object", "required": [ "prompt", "images" ], "title": "ImageEditIn", "example": { "images": [ "6f1c2b9e-7d4a-4c8e-9b3f-2a5d8e1c4f70" ], "prompt": "Make the sky stormy and add rain" } }, "ImageGenerationIn": { "properties": { "prompt": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Prompt", "description": "What the image shows. Text to appear in it goes in quotes." }, "reference_images": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 8 }, { "type": "null" } ], "title": "Reference Images", "description": "Up to 8 images (file ids) whose look or subjects the new image draws on." } }, "additionalProperties": false, "type": "object", "required": [ "prompt" ], "title": "ImageGenerationIn", "example": { "prompt": "A watercolor lighthouse at dawn, in soft pastel light" } }, "ImageOut": { "properties": { "object": { "type": "string", "const": "image", "title": "Object", "default": "image" }, "id": { "type": "string", "title": "Id", "description": "The generation's identifier." }, "type": { "type": "string", "enum": [ "generate", "edit" ], "title": "Type", "description": "`generate` (from a description) or `edit` (from the caller's images)." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ], "title": "Status", "description": "`queued`, then `running`; it ends `completed`, `failed` or `canceled` and does not change after that." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/GenerationErrorOut" }, { "type": "null" } ], "description": "Why it failed, when `status` is `failed`." }, "files": { "items": { "$ref": "#/components/schemas/FileOut" }, "type": "array", "title": "Files", "description": "The results, once `completed` — the caller's own files from then on." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" } }, "type": "object", "required": [ "id", "type", "status", "created_at" ], "title": "ImageOut" }, "ListOut_ImageOut_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/ImageOut" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ListOut[ImageOut]" }, "ListOut_MessageOut_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/MessageOut" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ListOut[MessageOut]" }, "ListOut_MusicOut_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/MusicOut" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ListOut[MusicOut]" }, "ListOut_SessionOut_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/SessionOut" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ListOut[SessionOut]" }, "ListOut_UserOut_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/UserOut" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ListOut[UserOut]" }, "ListOut_VideoOut_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/VideoOut" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ListOut[VideoOut]" }, "MeOut": { "properties": { "object": { "type": "string", "const": "user", "title": "Object", "default": "user" }, "id": { "type": "string", "title": "Id" }, "project": { "$ref": "#/components/schemas/MeProjectOut" } }, "type": "object", "required": [ "id", "project" ], "title": "MeOut" }, "MeProjectOut": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "MeProjectOut" }, "MessageAttachmentOut": { "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio", "file" ], "title": "Type" }, "filename": { "type": "string", "title": "Filename" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "type", "filename" ], "title": "MessageAttachmentOut", "description": "One asset on a message — an image, a video, audio, or a file (a document the task\nproduced) — with a download link valid for an hour (until ``expires_at``); ``url`` is\n``null`` when the asset can no longer be served." }, "MessageIn": { "properties": { "text": { "type": "string", "maxLength": 32000, "minLength": 1, "title": "Text", "description": "What the end user says in this turn." }, "attachments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AttachmentIn" }, "type": "array", "maxItems": 10 }, { "type": "null" } ], "title": "Attachments", "description": "Media to attach to this turn (up to 10 items). `null` or an empty list means no media." }, "a2ui_action": { "anyOf": [ { "$ref": "#/components/schemas/A2uiActionIn" }, { "type": "null" } ], "description": "Set when the user sent this message by acting on an `a2ui` surface (a button tap, a form submit): the renderer's a2ui `action` message, as is. `text` still holds what the user sees themselves send, such as the button's label. Only an `a2ui` session takes one." }, "stream": { "type": "boolean", "title": "Stream", "description": "`true` to receive the task on this request: the response is a stream of the task's own frames, as the session's event stream sends them, from its first frame through its end frame — or for at most 10 minutes, like any event stream.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "MessageIn", "description": "One message from the end user: the text of the turn, plus optional media.", "example": { "text": "What should I pack for three days in Lisbon in March?" } }, "MessageOut": { "properties": { "object": { "type": "string", "const": "message", "title": "Object", "default": "message" }, "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "enum": [ "user_message", "assistant_message", "activity", "status_update" ], "title": "Type" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "error": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Error" }, "attachments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MessageAttachmentOut" }, "type": "array" }, { "type": "null" } ], "title": "Attachments" }, "suggestions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Suggestions" }, "activity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Activity" } }, "type": "object", "required": [ "id", "type" ], "title": "MessageOut" }, "MotionTransferIn": { "properties": { "quality": { "type": "string", "enum": [ "standard", "pro" ], "title": "Quality", "description": "`standard`, or `pro` for a sharper result. Defaults to `standard`.", "default": "standard" }, "image": { "type": "string", "format": "uuid", "title": "Image", "description": "An image (file id) of the person to animate." }, "video": { "type": "string", "format": "uuid", "title": "Video", "description": "The source video (a file id) whose motion the person follows." }, "follow": { "type": "string", "enum": [ "image", "video" ], "title": "Follow", "description": "Whose framing and facing the result keeps: `image` (the source video may be up to 10 seconds) or `video` (up to 30 seconds)." }, "prompt": { "anyOf": [ { "type": "string", "maxLength": 2500, "minLength": 1 }, { "type": "null" } ], "title": "Prompt", "description": "Optional details about the scene or the person." }, "keep_audio": { "type": "boolean", "title": "Keep Audio", "description": "Keep the source video's sound. Defaults to true.", "default": true }, "start_seconds": { "anyOf": [ { "type": "number", "maximum": 86400, "minimum": 0 }, { "type": "null" } ], "title": "Start Seconds", "description": "Where the part of the source video to use begins, in seconds. Needed only when the source is longer than this operation takes; without it such a generation fails with `invalid_input`." } }, "additionalProperties": false, "type": "object", "required": [ "image", "video", "follow" ], "title": "MotionTransferIn", "example": { "follow": "image", "image": "6f1c2b9e-7d4a-4c8e-9b3f-2a5d8e1c4f70", "video": "a3d5e7f9-1b2c-4d6e-8f0a-9c7b5d3e1f24" } }, "MusicCreateIn": { "properties": { "prompt": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Prompt", "description": "What the music is: its subject, instruments, voice or lyrics." }, "duration_seconds": { "anyOf": [ { "type": "integer", "maximum": 300, "minimum": 10 }, { "type": "null" } ], "title": "Duration Seconds", "description": "Preferred length in seconds — a hint only: the result is usually a full song of about two minutes." }, "genre": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Genre", "description": "Optional genre, e.g. `lo-fi hip hop`." }, "mood": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Mood", "description": "Optional mood, e.g. `calm`." }, "tempo": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Tempo", "description": "Optional tempo, e.g. `slow` or `120 bpm`." } }, "additionalProperties": false, "type": "object", "required": [ "prompt" ], "title": "MusicCreateIn", "example": { "duration_seconds": 30, "mood": "calm", "prompt": "Warm acoustic guitar for a slow morning" } }, "MusicOut": { "properties": { "object": { "type": "string", "const": "music", "title": "Object", "default": "music" }, "id": { "type": "string", "title": "Id", "description": "The generation's identifier." }, "type": { "type": "string", "const": "generate", "title": "Type", "description": "`generate`." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ], "title": "Status", "description": "`queued`, then `running`; it ends `completed`, `failed` or `canceled` and does not change after that." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/GenerationErrorOut" }, { "type": "null" } ], "description": "Why it failed, when `status` is `failed`." }, "files": { "items": { "$ref": "#/components/schemas/FileOut" }, "type": "array", "title": "Files", "description": "The results, once `completed` — the caller's own files from then on." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" } }, "type": "object", "required": [ "id", "type", "status", "created_at" ], "title": "MusicOut" }, "RealtimeSessionIn": { "properties": { "session_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Session Id", "description": "A voice session of the caller's that has not ended, to rejoin with a fresh secret; omit it to start a new one. A rejoined session keeps the capabilities it was created with, so leave out `capabilities` and `exclude_capabilities`." }, "capabilities": { "anyOf": [ { "items": { "type": "string", "enum": [ "search", "deep_research", "understanding", "image_generation", "video_generation", "music_generation", "documents" ] }, "type": "array" }, { "type": "null" } ], "title": "Capabilities", "description": "Open only these capabilities in this session: the assistant uses no other, and a capability added later never reaches it. An empty list leaves the assistant only its conversation — and its memory of the user, which every session keeps. Leave out both this and `exclude_capabilities` to open every capability. Fixed for the session's life." }, "exclude_capabilities": { "anyOf": [ { "items": { "type": "string", "enum": [ "search", "deep_research", "understanding", "image_generation", "video_generation", "music_generation", "documents" ] }, "type": "array" }, { "type": "null" } ], "title": "Exclude Capabilities", "description": "Open every capability but these in this session. A capability added later opens in the sessions created after it is added; this one keeps the ones it was created with. Send this or `capabilities`, not both. Fixed for the session's life." } }, "additionalProperties": false, "type": "object", "title": "RealtimeSessionIn", "example": { "capabilities": [ "search" ] } }, "RealtimeSessionOut": { "properties": { "object": { "type": "string", "const": "realtime_session", "title": "Object", "default": "realtime_session" }, "id": { "type": "string", "title": "Id", "description": "Identifier of the voice session (`GET /v1/sessions/{session_id}`)." }, "client_secret": { "$ref": "#/components/schemas/ClientSecretOut" }, "websocket_url": { "type": "string", "title": "Websocket Url", "description": "Absolute wss:// URL the client opens, with the secret, to start the voice stream." }, "model": { "type": "string", "title": "Model" } }, "type": "object", "required": [ "id", "client_secret", "websocket_url", "model" ], "title": "RealtimeSessionOut" }, "SessionCreateIn": { "properties": { "text": { "anyOf": [ { "type": "string", "maxLength": 32000, "minLength": 1 }, { "type": "null" } ], "title": "Text", "description": "Optional first message: what the end user says. When given, the session's first turn starts right away and its `task_id` is returned." }, "attachments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AttachmentIn" }, "type": "array", "maxItems": 10 }, { "type": "null" } ], "title": "Attachments", "description": "Media to attach to this turn (up to 10 items). `null` or an empty list means no media." }, "capabilities": { "anyOf": [ { "items": { "type": "string", "enum": [ "search", "deep_research", "understanding", "image_generation", "video_generation", "music_generation", "documents" ] }, "type": "array" }, { "type": "null" } ], "title": "Capabilities", "description": "Open only these capabilities in this session: the assistant uses no other, and a capability added later never reaches it. An empty list leaves the assistant only its conversation — and its memory of the user, which every session keeps. Leave out both this and `exclude_capabilities` to open every capability. Fixed for the session's life." }, "exclude_capabilities": { "anyOf": [ { "items": { "type": "string", "enum": [ "search", "deep_research", "understanding", "image_generation", "video_generation", "music_generation", "documents" ] }, "type": "array" }, { "type": "null" } ], "title": "Exclude Capabilities", "description": "Open every capability but these in this session. A capability added later opens in the sessions created after it is added; this one keeps the ones it was created with. Send this or `capabilities`, not both. Fixed for the session's life." }, "output_format": { "type": "string", "enum": [ "a2ui", "markdown" ], "title": "Output Format", "description": "Reply form for this session, fixed for its life: `a2ui` for UI data, with the words the reply says outside that UI as plain text, or `markdown` for formatted text. Defaults to `a2ui`.", "default": "a2ui" } }, "additionalProperties": false, "type": "object", "title": "SessionCreateIn", "example": { "text": "Find three quiet cafés near Union Square that are open after 8 pm." } }, "SessionCreatedOut": { "properties": { "object": { "type": "string", "const": "session", "title": "Object", "default": "session" }, "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "enum": [ "text", "realtime" ], "title": "Type" }, "status": { "type": "string", "enum": [ "created", "queued", "running", "completed", "failed", "stopped", "timeout" ], "title": "Status" }, "output_format": { "type": "string", "title": "Output Format" }, "brief_status": { "type": "string", "enum": [ "none", "running", "completed" ], "title": "Brief Status", "default": "none" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ended At" }, "capabilities": { "items": { "type": "string", "enum": [ "search", "deep_research", "understanding", "image_generation", "video_generation", "music_generation", "documents" ] }, "type": "array", "title": "Capabilities", "description": "The capabilities the assistant may use in this session, fixed when it was created." }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "last_event_id": { "type": "string", "title": "Last Event Id", "description": "Where this task's frames begin on the session's event stream: open `GET /v1/sessions/{session_id}/events` with `Last-Event-ID` set to it to receive the task from its first frame. `0` means from the session's start.", "default": "0" } }, "type": "object", "required": [ "id", "type", "status", "output_format", "created_at" ], "title": "SessionCreatedOut", "description": "201 body of ``POST /v1/sessions``: the new session, plus the ``task_id`` of the\nfirst turn when a first message was sent, and where its events begin." }, "SessionOut": { "properties": { "object": { "type": "string", "const": "session", "title": "Object", "default": "session" }, "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "enum": [ "text", "realtime" ], "title": "Type" }, "status": { "type": "string", "enum": [ "created", "queued", "running", "completed", "failed", "stopped", "timeout" ], "title": "Status" }, "output_format": { "type": "string", "title": "Output Format" }, "brief_status": { "type": "string", "enum": [ "none", "running", "completed" ], "title": "Brief Status", "default": "none" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ended At" }, "capabilities": { "items": { "type": "string", "enum": [ "search", "deep_research", "understanding", "image_generation", "video_generation", "music_generation", "documents" ] }, "type": "array", "title": "Capabilities", "description": "The capabilities the assistant may use in this session, fixed when it was created." } }, "type": "object", "required": [ "id", "type", "status", "output_format", "created_at" ], "title": "SessionOut" }, "SoundtrackIn": { "properties": { "video": { "type": "string", "format": "uuid", "title": "Video", "description": "The source video (a file id) whose sound is replaced." }, "audio": { "type": "string", "format": "uuid", "title": "Audio", "description": "The audio clip (a file id) to play over it." }, "audio_start_seconds": { "type": "number", "maximum": 86400, "minimum": 0, "title": "Audio Start Seconds", "description": "Where in the audio clip to start, in seconds. Defaults to 0.", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "video", "audio" ], "title": "SoundtrackIn", "example": { "audio": "c8b6a4d2-e0f1-4a3b-9c5d-7e9f1a2b3c46", "video": "a3d5e7f9-1b2c-4d6e-8f0a-9c7b5d3e1f24" } }, "TaskRefOut": { "properties": { "object": { "type": "string", "const": "task", "title": "Object", "default": "task" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "task_id", "session_id" ], "title": "TaskRefOut", "description": "The turn a request started or stopped: ``POST /v1/sessions/{id}/messages``\n(always a ``task_id``) and ``POST /v1/sessions/{id}/stop`` (``null`` when no turn\nwas running). The turn's output arrives on the session's event stream and in its\nmessage list, tagged with this ``task_id``." }, "TaskStartedOut": { "properties": { "object": { "type": "string", "const": "task", "title": "Object", "default": "task" }, "task_id": { "type": "string", "title": "Task Id" }, "session_id": { "type": "string", "title": "Session Id" }, "last_event_id": { "type": "string", "title": "Last Event Id", "description": "Where this task's frames begin on the session's event stream: open `GET /v1/sessions/{session_id}/events` with `Last-Event-ID` set to it to receive the task from its first frame. `0` means from the session's start." } }, "type": "object", "required": [ "task_id", "session_id", "last_event_id" ], "title": "TaskStartedOut", "description": "202 body of ``POST /v1/sessions/{id}/messages``: the task the message started, and\nwhere its frames begin on the session's event stream." }, "TokenIssueIn": { "properties": { "expires_in": { "anyOf": [ { "type": "integer", "maximum": 86400, "minimum": 60 }, { "type": "null" } ], "title": "Expires In", "description": "Token lifetime in seconds; omit to use the default lifetime." } }, "additionalProperties": false, "type": "object", "title": "TokenIssueIn", "example": { "expires_in": 3600 } }, "TokenIssueOut": { "properties": { "object": { "type": "string", "const": "token", "title": "Object", "default": "token" }, "token": { "type": "string", "title": "Token" }, "token_type": { "type": "string", "const": "bearer", "title": "Token Type", "default": "bearer" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "When the token expires." } }, "type": "object", "required": [ "token", "expires_at" ], "title": "TokenIssueOut" }, "TranscriptionOut": { "properties": { "object": { "type": "string", "const": "transcription", "title": "Object", "default": "transcription" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "TranscriptionOut" }, "UserCreateIn": { "properties": { "issue_token": { "type": "boolean", "title": "Issue Token", "description": "Also issue the new user a token, returned as `token`: the user's first, saving a call to Issue user token. Later ones come from that operation.", "default": false }, "expires_in": { "anyOf": [ { "type": "integer", "maximum": 86400, "minimum": 60 }, { "type": "null" } ], "title": "Expires In", "description": "Token lifetime in seconds; omit to use the default lifetime. Send it only with `issue_token: true`." } }, "additionalProperties": false, "type": "object", "title": "UserCreateIn", "example": { "expires_in": 3600, "issue_token": true } }, "UserCreatedOut": { "properties": { "object": { "type": "string", "const": "user", "title": "Object", "default": "user" }, "id": { "type": "string", "title": "Id" }, "is_active": { "type": "boolean", "title": "Is Active" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "token": { "anyOf": [ { "$ref": "#/components/schemas/TokenIssueOut" }, { "type": "null" } ], "description": "The user's first token, when the request asked for one (`issue_token`)." } }, "type": "object", "required": [ "id", "is_active", "created_at" ], "title": "UserCreatedOut" }, "UserOut": { "properties": { "object": { "type": "string", "const": "user", "title": "Object", "default": "user" }, "id": { "type": "string", "title": "Id" }, "is_active": { "type": "boolean", "title": "Is Active" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "is_active", "created_at" ], "title": "UserOut" }, "UserPatchIn": { "properties": { "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Set false to disable the user or true to re-enable; omit to leave it unchanged." } }, "additionalProperties": false, "type": "object", "title": "UserPatchIn", "example": { "is_active": false } }, "VideoCreateIn": { "properties": { "quality": { "type": "string", "enum": [ "standard", "pro" ], "title": "Quality", "description": "`standard`, or `pro` for reference media, up to 15 seconds and 4k resolution. Defaults to `standard`.", "default": "standard" }, "prompt": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Prompt", "description": "What happens in the video." }, "first_frame": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "First Frame", "description": "An image (file id) the video starts from." }, "last_frame": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Last Frame", "description": "An image (file id) the video ends on. Requires `first_frame`." }, "reference_images": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 9 }, { "type": "null" } ], "title": "Reference Images", "description": "`pro` only: up to 9 images (file ids) whose subjects or look the video follows. Not together with `first_frame` / `last_frame`." }, "reference_videos": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 3 }, { "type": "null" } ], "title": "Reference Videos", "description": "`pro` only: up to 3 videos (file ids), 15 seconds together at most, whose motion or camera work the video follows." }, "reference_audios": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 3 }, { "type": "null" } ], "title": "Reference Audios", "description": "`pro` only: up to 3 audio clips (file ids) for the video's sound. Needs at least one reference image or video." }, "duration": { "type": "integer", "maximum": 15, "minimum": 4, "title": "Duration", "description": "Length in seconds: 4–12 (`pro`: up to 15). Defaults to 5.", "default": 5 }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "auto" ], "title": "Aspect Ratio", "description": "The frame's shape; `auto` follows the inputs. Defaults to `auto`.", "default": "auto" }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p", "4k" ], "title": "Resolution", "description": "`480p`, `720p` or `1080p` (`pro`: also `4k`). Defaults to `720p`.", "default": "720p" }, "audio": { "type": "boolean", "title": "Audio", "description": "Give the video sound. Defaults to true.", "default": true } }, "additionalProperties": false, "type": "object", "required": [ "prompt" ], "title": "VideoCreateIn", "example": { "prompt": "A paper boat drifting down a rainy street, the camera following it" } }, "VideoEditIn": { "properties": { "quality": { "type": "string", "enum": [ "standard", "pro" ], "title": "Quality", "description": "`standard`, or `pro` for 1080p output. Defaults to `standard`.", "default": "standard" }, "video": { "type": "string", "format": "uuid", "title": "Video", "description": "The source video (a file id), 3 to 15 seconds long." }, "prompt": { "type": "string", "maxLength": 2500, "minLength": 1, "title": "Prompt", "description": "The change to make; the rest of the video — its length and its shots — stays the same." }, "reference_images": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 4 }, { "type": "null" } ], "title": "Reference Images", "description": "Up to 4 images (file ids) of what to bring into the video." }, "keep_audio": { "type": "boolean", "title": "Keep Audio", "description": "Keep the source video's sound. Defaults to true.", "default": true }, "start_seconds": { "anyOf": [ { "type": "number", "maximum": 86400, "minimum": 0 }, { "type": "null" } ], "title": "Start Seconds", "description": "Where the part of the source video to use begins, in seconds. Needed only when the source is longer than this operation takes; without it such a generation fails with `invalid_input`." } }, "additionalProperties": false, "type": "object", "required": [ "video", "prompt" ], "title": "VideoEditIn", "example": { "prompt": "Turn the daytime scene into a snowy night", "video": "a3d5e7f9-1b2c-4d6e-8f0a-9c7b5d3e1f24" } }, "VideoOut": { "properties": { "object": { "type": "string", "const": "video", "title": "Object", "default": "video" }, "id": { "type": "string", "title": "Id", "description": "The generation's identifier." }, "type": { "type": "string", "enum": [ "generate", "edit", "remake", "motion_transfer", "reframe", "soundtrack" ], "title": "Type", "description": "`generate`, `edit`, `remake`, `motion_transfer`, `reframe` or `soundtrack` — the operation that made it." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ], "title": "Status", "description": "`queued`, then `running`; it ends `completed`, `failed` or `canceled` and does not change after that." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/GenerationErrorOut" }, { "type": "null" } ], "description": "Why it failed, when `status` is `failed`." }, "files": { "items": { "$ref": "#/components/schemas/FileOut" }, "type": "array", "title": "Files", "description": "The results, once `completed` — the caller's own files from then on." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" } }, "type": "object", "required": [ "id", "type", "status", "created_at" ], "title": "VideoOut" }, "VideoReframeIn": { "properties": { "video": { "type": "string", "format": "uuid", "title": "Video", "description": "The source video (a file id), up to 60 seconds long." }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "4:5", "5:4", "9:16", "16:9" ], "title": "Aspect Ratio", "description": "The new frame's shape." }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ], "title": "Resolution", "description": "`720p` or `1080p`. Defaults to `1080p`.", "default": "1080p" }, "start_seconds": { "anyOf": [ { "type": "number", "maximum": 86400, "minimum": 0 }, { "type": "null" } ], "title": "Start Seconds", "description": "Where the part of the source video to use begins, in seconds. Needed only when the source is longer than this operation takes; without it such a generation fails with `invalid_input`." } }, "additionalProperties": false, "type": "object", "required": [ "video", "aspect_ratio" ], "title": "VideoReframeIn", "example": { "aspect_ratio": "9:16", "video": "a3d5e7f9-1b2c-4d6e-8f0a-9c7b5d3e1f24" } }, "VideoRemakeIn": { "properties": { "video": { "type": "string", "format": "uuid", "title": "Video", "description": "The source video (a file id) to shoot a new take after." }, "prompt": { "type": "string", "maxLength": 2500, "minLength": 1, "title": "Prompt", "description": "What the new take shows." }, "reference_images": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 4 }, { "type": "null" } ], "title": "Reference Images", "description": "Up to 4 images (file ids) of what to bring into the take." }, "aspect_ratio": { "type": "string", "enum": [ "auto", "16:9", "9:16", "1:1" ], "title": "Aspect Ratio", "description": "The frame's shape; `auto` follows the source. Defaults to `auto`.", "default": "auto" }, "duration": { "anyOf": [ { "type": "integer", "maximum": 15, "minimum": 3 }, { "type": "null" } ], "title": "Duration", "description": "Length in seconds, 3–15. Omit to follow the source." }, "keep_audio": { "type": "boolean", "title": "Keep Audio", "description": "Keep the source video's sound. Defaults to true.", "default": true }, "start_seconds": { "anyOf": [ { "type": "number", "maximum": 86400, "minimum": 0 }, { "type": "null" } ], "title": "Start Seconds", "description": "Where the part of the source video to use begins, in seconds. Needed only when the source is longer than this operation takes; without it such a generation fails with `invalid_input`." } }, "additionalProperties": false, "type": "object", "required": [ "video", "prompt" ], "title": "VideoRemakeIn", "example": { "duration": 5, "prompt": "The same scene, shot as a hand-drawn animation", "video": "a3d5e7f9-1b2c-4d6e-8f0a-9c7b5d3e1f24" } } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "A project secret, or a user token issued by the tokens endpoint.", "scheme": "bearer" } } }, "servers": [ { "url": "https://open-api-beta.viagent.collov.ai", "description": "The API base URL shown in the console" } ] }