{ "openapi": "3.0.3", "info": { "title": "FacePick local developer API", "version": "2.0.0", "description": "Sandbox developer API. Approved calls accrue USD cents; no payments or automatic failure refunds. Adult/political disabled." }, "servers": [ { "url": "http://127.0.0.1:3110", "description": "Ordinary local integration preview. Automated tests use an isolated server/database on port 3111, overriding this server URL." } ], "security": [ { "ApplicationKey": [] } ], "paths": { "/api/developer/whoami": { "get": { "operationId": "getApplicationIdentity", "summary": "Read application identity", "description": "Reads current key ownership; no license consumption or generation.", "responses": { "200": { "description": "Successful operation. Data includes sandbox records, not commercial likeness rights.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityResponse" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developer/faces": { "get": { "operationId": "searchFaces", "summary": "Search published public face assets", "description": "Returns at most 100 safe records, sorted by FaceID. Search matches name, description or FaceID literally; no pagination parameters. Querying does not grant usage rights. Authenticated result/failure is recorded in API usage; storage failure fails the request.", "responses": { "200": { "description": "Successful operation. Data includes sandbox records, not commercial likeness rights.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacesResponse" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields, scope or media. Runtime rights/state checks are additional to schema validation.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Local/test sandbox unavailable; production providers are not configured.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Optional literal search, trimmed by server.", "schema": { "type": "string", "maxLength": 100 } } ] } }, "/api/developer/faces/{faceId}": { "get": { "operationId": "getFace", "summary": "Read a published public asset", "description": "Only published safe DTO; nonexistent, paused and invalid IDs return 404. No private identity/capture data. Querying does not grant usage rights.", "responses": { "200": { "description": "Successful operation. Data includes sandbox records, not commercial likeness rights.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceResponse" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Object not found, unavailable, or not owned by this application.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Local/test sandbox unavailable; production providers are not configured.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "faceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/developer/license-uses": { "post": { "operationId": "useLicense", "summary": "Consume one valid licensed use", "description": "Requires paid active license for this exact Application and published asset. Scope and training permission checked independently. Successful first use consumes one count atomically. Persist idempotencyKey before sending: same Application + idempotencyKey + payload replays the original receipt without consuming again, including through another valid Key of that Application; different payload conflicts. Receipt is not a generation task. Replaying history after suspension/expiry does not authorize new use. JSON body at most 16 KiB. Revoked keys cannot replay.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseUseInput" } } } }, "responses": { "200": { "description": "Successful operation. Data includes sandbox records, not commercial likeness rights.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseUseResponse" } } } }, "400": { "description": "Invalid JSON request body.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Untrusted Origin on write requests. Server-to-server Bearer requests may omit Origin; a supplied Origin must match the configured service origin.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Object not found, unavailable, or not owned by this application.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict; use may be inactive or quota exhausted. Query original state before retrying a write; never change a stable key just to bypass a conflict. LICENSE_TERMS_REQUIRED.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds endpoint limit.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields, scope or media. Runtime rights/state checks are additional to schema validation. ROLE_CONSENT_REQUIRED, SCENE_DENIED, MINOR_ADULT_FORBIDDEN.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: too many requests for this API Key or client IP within the current window. Counted before authentication. If the rate-limit store is unavailable this endpoint fails open.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Local/test sandbox unavailable; production providers are not configured.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developer/contents": { "post": { "operationId": "submitContent", "summary": "Return actual content for a use", "description": "Exact Application required. One Content per non-training Use; image/video MIME must match the use purpose. Actual decoded file at most 5 MiB, JSON body at most 7 MiB. No extra quota consumption. First creation is UNDER_REVIEW; same application/idempotencyKey and same content replay its current status (possibly APPROVED or REJECTED) with 201. Different payload or duplicate Use conflicts. Manual approval is not public publishing or real-world rights clearance. Store a stable idempotencyKey and reuse unchanged parameters on uncertain retries. New ledger uses fail closed with AI_LABEL_REQUIRED until a trusted final-byte AI-label verifier is integrated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentInput" } } } }, "responses": { "201": { "description": "Successful operation. Data includes sandbox records, not commercial likeness rights.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentResponse" } } } }, "400": { "description": "Invalid JSON request body.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Untrusted Origin on write requests. Server-to-server Bearer requests may omit Origin; a supplied Origin must match the configured service origin.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Object not found, unavailable, or not owned by this application.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict; use may be inactive or quota exhausted. Query original state before retrying a write; never change a stable key just to bypass a conflict.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds endpoint limit.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields, scope or media. Runtime rights/state checks are additional to schema validation.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Local/test sandbox unavailable; production providers are not configured.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developer/faces/page": { "get": { "operationId": "searchFacesPage", "summary": "Page through published public assets", "description": "Returns items and nextCursor, sorted by FaceID. Repeat with the same q and returned cursor until nextCursor is null. Default limit20/max100. Every page authenticates the current Application Key and logs the attempt; log storage failure fails closed. Cursor binds the trimmed search, not an authorization grant. Each page queries current PUBLISHED assets, not a frozen snapshot across pages.", "responses": { "200": { "description": "Successful operation. Data includes sandbox records, not commercial likeness rights.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacesPageResponse" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields, scope or media. Runtime rights/state checks are additional to schema validation.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Local/test sandbox unavailable; production providers are not configured.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Optional literal search, trimmed by server.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Opaque cursor from previous page; preserve the same q." } ] } }, "/api/health": { "get": { "operationId": "getLiveness", "summary": "Public liveness probe", "description": "Process liveness only; no dependency checks, no authentication, no internal details.", "security": [], "responses": { "200": { "description": "Process is up.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LivenessResponse" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/readiness": { "get": { "operationId": "getReadiness", "summary": "Administrator readiness check", "description": "Checks configuration and PostgreSQL. Redis and storage are reserved slots reporting not_configured until wired.", "security": [ { "AdminSession": [] } ], "responses": { "200": { "description": "All required checks pass.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } }, "401": { "description": "UNAUTHENTICATED: no valid session.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN: not an administrator.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required check failed.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } } } } }, "/api/developer/licenses": { "get": { "tags": [ "licenses" ], "operationId": "developerLicenses", "summary": "Developer team license list (paginated)", "description": "Console session with active team read access; licenses for applications owned by the team.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "assetId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "REVOKED", "PENDING" ] } } ], "responses": { "200": { "description": "License page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensePageResponse" } } } }, "401": { "description": "UNAUTHENTICATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "METHOD_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR or INVALID_INPUT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SignedInSession": [] } ] } }, "/api/developer/licenses/{licenseId}": { "get": { "tags": [ "licenses" ], "operationId": "developerLicenseDetail", "summary": "Developer team license detail", "parameters": [ { "name": "licenseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "License detail with optional terms snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseDetailResponse" } } } }, "401": { "description": "UNAUTHENTICATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "METHOD_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SignedInSession": [] } ] } }, "/api/developer/usage-ledger": { "get": { "operationId": "listUsageLedger", "parameters": [ { "name": "licenseId", "in": "query", "schema": { "type": "string" } }, { "name": "assetId", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "401": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only accrued sandbox ledger", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/UsageLedgerPage" }, "requestId": { "type": "string" } } } } } } } } }, "/api/developer/usage-ledger/{id}": { "get": { "operationId": "getUsageLedger", "parameters": [ { "name": "licenseId", "in": "query", "schema": { "type": "string" } }, { "name": "assetId", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Authentication, authorization, validation or method error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only accrued sandbox ledger", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/UsageLedgerEntry" }, "requestId": { "type": "string" } } } } } } } } }, "/api/developer/generations": { "post": { "operationId": "createGeneration", "summary": "Generate one AI-labelled image against a licensed use (sandbox, mock provider)", "description": "Debits exactly one licensed use BEFORE generation (same rules and idempotency as useLicense). A charged use is never auto-refunded: if the provider or storage fails the call returns 502 GENERATION_FAILED and a FAILED generation record is kept. Replaying the same Application + idempotencyKey + payload returns the original generation without charging or generating again. The AI label (aiGenerated, provenance) is set by the server only; any request field named aiGenerated, provenance, ai_generated or aiLabel (top level or nested) is rejected with 422 AI_LABEL_SERVER_OWNED. Image bytes are stored privately and are not exposed by URL in this version. No refund on failure: the licensed use is charged before generation; a failed generation keeps an append-only FAILED record and returns 502. Retrying with the same idempotencyKey returns that FAILED record (200/201 replay, no new generation); a new attempt needs a NEW idempotencyKey and charges another use.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationInput" } } } }, "responses": { "201": { "description": "Generation record created (or replayed).", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" } } } }, "400": { "description": "Invalid JSON request body.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED: missing, invalid or revoked API Key. Cookie does not replace Bearer.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Untrusted Origin on write requests. Server-to-server Bearer requests may omit Origin; a supplied Origin must match the configured service origin.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Object not found, unavailable, or not owned by this application.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not supported.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict; use may be inactive or quota exhausted. Query original state before retrying a write; never change a stable key just to bypass a conflict. LICENSE_TERMS_REQUIRED when the license has no confirmed usage terms; LEDGER_ENTRY_REQUIRED when the idempotencyKey replays a pre-ledger licensed use (use a new key).", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds endpoint limit.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error (including an invalid scene), license scope denied, scene/role-consent denied by the usage ledger rules (SCENE_DENIED, MINOR_ADULT_FORBIDDEN, ROLE_CONSENT_REQUIRED), or AI_LABEL_SERVER_OWNED.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; safe message and requestId only.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "GENERATION_FAILED: provider or storage failed after the use was charged; no automatic refund. The use stays charged (no refund). Same idempotencyKey replays the FAILED record; use a new key to try again (charges again).", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Local/test sandbox unavailable; production providers are not configured.", "headers": { "X-Request-ID": { "description": "Correlation ID for this HTTP attempt; may differ from an idempotently replayed record's original requestId.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "generations" ] }, "get": { "tags": [ "generations" ], "operationId": "listGenerations", "summary": "List this application's generation records (newest first)", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque; bound to the calling key/application and the filters." }, { "name": "licenseId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ] } } ], "responses": { "200": { "description": "Generation page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationPageResponse" } } } }, "401": { "description": "UNAUTHENTICATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR (unknown/repeated parameter, bad limit/licenseId/status, bad or mis-bound cursor)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developer/generations/{id}": { "get": { "tags": [ "generations" ], "operationId": "getGeneration", "summary": "One generation record of this application", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Generation record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRecordResponse" } } } }, "401": { "description": "UNAUTHENTICATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND (missing or another application's record)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "METHOD_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developer/generations/{id}/content": { "get": { "tags": [ "generations" ], "operationId": "getGenerationContent", "summary": "Download the generated image bytes (private, never a public URL)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image bytes", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\"generation-.png\"" }, "X-Content-SHA256": { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "Cache-Control": { "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Reserved for COS storage: redirects to a short-lived signed URL (expiry <= 3600 seconds). Local storage keeps returning 200 with the bytes.", "headers": { "Location": { "description": "Short-lived signed URL of the private object (expires within 3600 seconds).", "schema": { "type": "string", "format": "uri" } }, "X-Content-SHA256": { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "Cache-Control": { "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "401": { "description": "UNAUTHENTICATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "METHOD_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "GENERATION_NOT_AVAILABLE (FAILED record, no content)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationNotAvailableError" } } } }, "410": { "description": "CONTENT_GONE (stored file missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentGoneError" } } } } } } }, "/api/developer/licenses/{licenseId}/usage-terms": { "get": { "tags": [ "usage-terms" ], "operationId": "getDeveloperLicenseUsageTermsStatus", "summary": "Licensee team: ethics versions, pending and confirmed usage terms", "security": [ { "SignedInSession": [] } ], "parameters": [ { "name": "licenseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "type": "object" }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "License not found for active team" } }, "description": "Returns confirmed terms, pending rows with full field summary, and counterpartSummary (other party's submitted fields) when status is PENDING_COUNTERPARTY." }, "post": { "tags": [ "usage-terms" ], "operationId": "confirmDeveloperLicenseUsageTerms", "summary": "Licensee submits or completes two-step usage-terms confirmation (trade capability)", "security": [ { "SignedInSession": [] } ], "parameters": [ { "name": "licenseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ethicsVersionId", "scenes", "unitCostCents", "referrerUserId", "referralEvidenceHash" ], "properties": { "ethicsVersionId": { "type": "string", "format": "uuid" }, "scenes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "short_drama", "advertisement", "education", "game" ] } }, "unitCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "referrerUserId": { "type": "string", "nullable": true, "format": "uuid" }, "referralEvidenceHash": { "type": "string", "nullable": true, "pattern": "^[0-9a-f]{64}$" } } } } } }, "responses": { "200": { "description": "PENDING_COUNTERPARTY or CONFIRMED", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "type": "object" }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "License not found" }, "409": { "description": "Already confirmed" }, "422": { "description": "Validation error" } } } } }, "components": { "securitySchemes": { "ApplicationKey": { "type": "http", "scheme": "bearer", "description": "Opaque fp_ API Key created for an Application, not a JWT or browser session. Full value shown once." }, "AdminSession": { "type": "apiKey", "in": "cookie", "name": "facepic_session", "description": "Console session cookie of an Admin or SuperAdmin user." }, "SignedInSession": { "type": "apiKey", "in": "cookie", "name": "facepic_session", "description": "Console session cookie of any signed-in account (no role required)." } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": { "type": "string" } } } }, "LicenseScope": { "type": "object", "additionalProperties": false, "required": [ "scenes", "regions", "maxUses", "commercial" ], "properties": { "scenes": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "string", "enum": [ "CN", "GLOBAL" ] } }, "maxUses": { "type": "integer", "nullable": true }, "commercial": { "type": "boolean" } } }, "LicenseItem": { "type": "object", "additionalProperties": false, "required": [ "licenseId", "assetId", "assetName", "assetCoverUrl", "developerId", "developerName", "applicationId", "applicationName", "status", "startsAt", "endsAt", "scope", "priceCents", "currency", "usedCount", "remainingUses", "worksCount", "orderId", "createdAt" ], "properties": { "licenseId": { "type": "string", "format": "uuid" }, "assetId": { "type": "string", "format": "uuid" }, "assetName": { "type": "string" }, "assetCoverUrl": { "type": "string", "nullable": true }, "developerId": { "type": "string", "format": "uuid" }, "developerName": { "type": "string" }, "applicationId": { "type": "string", "format": "uuid" }, "applicationName": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "REVOKED", "PENDING" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "scope": { "$ref": "#/components/schemas/LicenseScope" }, "priceCents": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD" ] }, "usedCount": { "type": "integer" }, "remainingUses": { "type": "integer", "nullable": true }, "worksCount": { "type": "integer" }, "orderId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" } } }, "LicenseTermsSnapshot": { "type": "object", "additionalProperties": false, "required": [ "snapshotId", "text", "hash", "createdAt" ], "properties": { "snapshotId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "hash": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "LicenseDetail": { "allOf": [ { "$ref": "#/components/schemas/LicenseItem" }, { "type": "object", "additionalProperties": false, "required": [ "terms" ], "properties": { "terms": { "$ref": "#/components/schemas/LicenseTermsSnapshot", "nullable": true } } } ] }, "LicensePage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LicenseItem" } }, "nextCursor": { "type": "string", "nullable": true } } }, "LicensePageResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/LicensePage" }, "requestId": { "type": "string" } } }, "LicenseDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/LicenseDetail" }, "requestId": { "type": "string" } } }, "Identity": { "type": "object", "additionalProperties": false, "required": [ "applicationId", "developerId" ], "properties": { "applicationId": { "type": "string", "format": "uuid" }, "developerId": { "type": "string", "format": "uuid" } } }, "Policy": { "type": "object", "additionalProperties": false, "required": [ "purposes", "channels", "territories", "termMonths", "usageCount", "trainingAllowed", "exclusive", "requireContentReview" ], "properties": { "purposes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "online", "offline" ] } }, "territories": { "type": "array", "items": { "type": "string", "enum": [ "CN", "GLOBAL" ] } }, "termMonths": { "type": "integer", "minimum": 1, "maximum": 60 }, "usageCount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "trainingAllowed": { "type": "boolean" }, "exclusive": { "type": "boolean" }, "requireContentReview": { "type": "boolean" } } }, "RoleType": { "type": "string", "enum": [ "REAL_PERSON", "VIRTUAL", "STYLIZED" ] }, "AssetScene": { "type": "string", "enum": [ "ADVERTISING", "ECOMMERCE", "FILM", "GAME", "EDUCATION", "SOCIAL", "OTHER" ] }, "ConfirmPolicy": { "type": "object", "additionalProperties": false, "description": "Forward shelf secondary confirm policy of one face asset. Unrelated to the reverse casting 72h respond_by window.", "required": [ "required", "withinHours", "bannerTextZh", "detailTextZh" ], "properties": { "required": { "type": "boolean" }, "withinHours": { "type": "integer", "minimum": 1, "maximum": 168 }, "bannerTextZh": { "type": "string" }, "detailTextZh": { "type": "string" } } }, "ContentThemeRef": { "type": "object", "additionalProperties": false, "required": [ "code", "labelZh" ], "properties": { "code": { "type": "string" }, "labelZh": { "type": "string" } } }, "ContentThemesView": { "type": "object", "additionalProperties": false, "description": "Checked themes are allowed, unchecked ones are not. While configured is false nothing is allowed yet: allowed is empty and blocked holds the whole active catalog.", "required": [ "configured", "allowed", "blocked", "footnoteZh" ], "properties": { "configured": { "type": "boolean" }, "allowed": { "type": "array", "items": { "$ref": "#/components/schemas/ContentThemeRef" } }, "blocked": { "type": "array", "items": { "$ref": "#/components/schemas/ContentThemeRef" } }, "footnoteZh": { "type": "string" } } }, "Face": { "type": "object", "additionalProperties": false, "description": "Published public face asset. GET /api/developer/faces/{faceId} always includes contentThemes; the search and page endpoints omit it and return confirmPolicy only.", "required": [ "faceId", "name", "description", "policy", "media", "roleType", "scenes", "coverUrl", "sandbox", "confirmPolicy" ], "properties": { "faceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "policy": { "$ref": "#/components/schemas/Policy" }, "media": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "sampleKey" ], "properties": { "sampleKey": { "type": "string" } } } }, "roleType": { "$ref": "#/components/schemas/RoleType" }, "scenes": { "type": "array", "items": { "$ref": "#/components/schemas/AssetScene" } }, "coverUrl": { "type": "string", "nullable": true }, "sandbox": { "type": "boolean", "enum": [ true ] }, "confirmPolicy": { "$ref": "#/components/schemas/ConfirmPolicy" }, "contentThemes": { "$ref": "#/components/schemas/ContentThemesView" } } }, "LicenseUseInput": { "type": "object", "additionalProperties": false, "required": [ "licenseId", "purpose", "channel", "territory", "training", "idempotencyKey", "scene" ], "properties": { "licenseId": { "type": "string", "format": "uuid" }, "purpose": { "type": "string", "enum": [ "image", "video" ] }, "channel": { "type": "string", "enum": [ "online", "offline" ] }, "territory": { "type": "string", "enum": [ "CN", "GLOBAL" ] }, "training": { "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" }, "scene": { "$ref": "#/components/schemas/Scene" } } }, "LicenseUse": { "type": "object", "additionalProperties": false, "required": [ "id", "licenseId", "orderId", "faceId", "applicationId", "requestId", "purpose", "channel", "territory", "training", "createdAt", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "licenseId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "faceId": { "type": "string", "format": "uuid" }, "applicationId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "purpose": { "type": "string", "enum": [ "image", "video" ] }, "channel": { "type": "string", "enum": [ "online", "offline" ] }, "territory": { "type": "string", "enum": [ "CN", "GLOBAL" ] }, "training": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] }, "usageId": { "type": "string" }, "settlementId": { "type": "string" }, "currency": { "type": "string" }, "hashStatus": { "type": "string" }, "legacy": { "type": "boolean" }, "costCents": { "$ref": "#/components/schemas/MoneyCents" } } }, "ContentInput": { "type": "object", "additionalProperties": false, "required": [ "useId", "title", "mimeType", "dataBase64", "idempotencyKey" ], "properties": { "useId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed nonempty title; disallowed control characters are rejected." }, "mimeType": { "type": "string", "enum": [ "image/png", "image/jpeg", "video/mp4" ] }, "dataBase64": { "type": "string", "format": "byte", "minLength": 4, "maxLength": 6990508, "description": "Canonical standard Base64 of actual file bytes, not a URL/data URL. Decoded bytes at most 5 MiB; JSON body at most 7 MiB. Basic media signatures checked, not malware scanning." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } } }, "Content": { "type": "object", "additionalProperties": false, "required": [ "id", "useId", "licenseId", "orderId", "faceId", "applicationId", "title", "status", "requireContentReview", "automaticReview", "mimeType", "byteCount", "sha256", "reason", "reviewedAt", "createdAt", "requestId", "useRequestId", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "useId": { "type": "string", "format": "uuid" }, "licenseId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "faceId": { "type": "string", "format": "uuid" }, "applicationId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "UNDER_REVIEW", "APPROVED", "REJECTED" ] }, "requireContentReview": { "type": "boolean" }, "automaticReview": { "type": "string", "enum": [ "NOT_CONFIGURED" ] }, "mimeType": { "type": "string", "enum": [ "image/png", "image/jpeg", "video/mp4" ] }, "byteCount": { "type": "integer", "minimum": 1, "maximum": 5242880 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "reason": { "type": "string", "nullable": true }, "reviewedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string", "format": "uuid" }, "useRequestId": { "type": "string", "format": "uuid" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "IdentityResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/Identity" }, "requestId": { "type": "string", "format": "uuid" } } }, "FacesResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Face" }, "maxItems": 100 }, "requestId": { "type": "string", "format": "uuid" } } }, "FaceResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/Face" }, "requestId": { "type": "string", "format": "uuid" } } }, "LicenseUseResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/LicenseUse" }, "requestId": { "type": "string", "format": "uuid" } } }, "ContentResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/Content" }, "requestId": { "type": "string", "format": "uuid" } } }, "FacesPageResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Face" } }, "nextCursor": { "type": "string", "nullable": true } } }, "requestId": { "type": "string", "format": "uuid" } } }, "CheckResult": { "type": "object", "additionalProperties": false, "required": [ "status", "durationMs" ], "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable", "not_configured" ] }, "durationMs": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } }, "Liveness": { "type": "object", "additionalProperties": false, "required": [ "status", "service", "now" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "now": { "type": "string", "format": "date-time" } } }, "LivenessResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/Liveness" }, "requestId": { "type": "string", "format": "uuid" } } }, "Readiness": { "type": "object", "additionalProperties": false, "required": [ "status", "checks" ], "properties": { "status": { "type": "string", "enum": [ "ready", "unavailable" ] }, "checks": { "type": "object", "additionalProperties": false, "required": [ "config", "database", "redis", "storage" ], "properties": { "config": { "$ref": "#/components/schemas/CheckResult" }, "database": { "$ref": "#/components/schemas/CheckResult" }, "redis": { "$ref": "#/components/schemas/CheckResult" }, "storage": { "$ref": "#/components/schemas/CheckResult" } } } } }, "ReadinessResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/Readiness" }, "requestId": { "type": "string", "format": "uuid" } } }, "Scene": { "type": "string", "enum": [ "short_drama", "advertisement", "education", "game", "adult", "political" ], "description": "adult and political always rejected in v1" }, "MoneyCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "example": "101", "readOnly": true }, "UsageLedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "useId", "licenseId", "assetId", "applicationId", "scene", "currency", "requestId", "occurredAt", "costCents", "contentHash", "hashStatus" ], "properties": { "id": { "type": "string", "readOnly": true }, "useId": { "type": "string", "readOnly": true }, "licenseId": { "type": "string", "readOnly": true }, "assetId": { "type": "string", "readOnly": true }, "applicationId": { "type": "string", "readOnly": true }, "scene": { "type": "string", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "requestId": { "type": "string", "readOnly": true }, "occurredAt": { "type": "string", "readOnly": true }, "costCents": { "$ref": "#/components/schemas/MoneyCents" }, "contentHash": { "type": "string", "nullable": true, "pattern": "^[0-9a-f]{64}$" }, "hashStatus": { "type": "string", "enum": [ "PENDING", "VERIFIED" ] } } }, "SettlementLedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "usageId", "currency", "occurredAt", "accountingState", "splitVersion", "grossCents", "ownerCents", "platformCents", "referrerCents", "unallocatedReferralCents" ], "properties": { "id": { "type": "string", "readOnly": true }, "usageId": { "type": "string", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "occurredAt": { "type": "string", "readOnly": true }, "accountingState": { "type": "string", "readOnly": true }, "splitVersion": { "type": "string", "readOnly": true }, "grossCents": { "$ref": "#/components/schemas/MoneyCents" }, "ownerCents": { "$ref": "#/components/schemas/MoneyCents" }, "platformCents": { "$ref": "#/components/schemas/MoneyCents" }, "referrerCents": { "$ref": "#/components/schemas/MoneyCents" }, "unallocatedReferralCents": { "$ref": "#/components/schemas/MoneyCents" } } }, "CreatorSettlementEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "usageId", "currency", "occurredAt", "accountingState", "ownerCents" ], "properties": { "id": { "type": "string", "readOnly": true }, "usageId": { "type": "string", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "occurredAt": { "type": "string", "readOnly": true }, "accountingState": { "type": "string", "readOnly": true }, "ownerCents": { "$ref": "#/components/schemas/MoneyCents" } } }, "UsageLedgerPage": { "type": "object", "additionalProperties": false, "required": [ "items", "summary", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLedgerEntry" } }, "summary": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "totalCents", "count" ], "properties": { "currency": { "type": "string" }, "totalCents": { "$ref": "#/components/schemas/MoneyCents" }, "count": { "$ref": "#/components/schemas/MoneyCents" } } } }, "nextCursor": { "type": "string", "nullable": true } } }, "SettlementLedgerPage": { "type": "object", "additionalProperties": false, "required": [ "items", "summary", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementLedgerEntry" } }, "summary": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "totalCents", "count" ], "properties": { "currency": { "type": "string" }, "totalCents": { "$ref": "#/components/schemas/MoneyCents" }, "count": { "$ref": "#/components/schemas/MoneyCents" } } } }, "nextCursor": { "type": "string", "nullable": true } } }, "CreatorSettlementPage": { "type": "object", "additionalProperties": false, "required": [ "items", "summary", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreatorSettlementEntry" } }, "summary": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "totalCents", "count" ], "properties": { "currency": { "type": "string" }, "totalCents": { "$ref": "#/components/schemas/MoneyCents" }, "count": { "$ref": "#/components/schemas/MoneyCents" } } } }, "nextCursor": { "type": "string", "nullable": true } } }, "GenerationInput": { "type": "object", "additionalProperties": false, "required": [ "licenseId", "purpose", "channel", "territory", "training", "idempotencyKey", "scene" ], "properties": { "licenseId": { "type": "string", "format": "uuid" }, "purpose": { "type": "string", "enum": [ "image", "video" ] }, "channel": { "type": "string", "enum": [ "online", "offline" ] }, "territory": { "type": "string", "enum": [ "CN", "GLOBAL" ] }, "training": { "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" }, "prompt": { "type": "string", "maxLength": 500 }, "scene": { "$ref": "#/components/schemas/Scene" } } }, "Generation": { "type": "object", "additionalProperties": false, "required": [ "id", "licenseUseId", "usageLedgerId", "licenseId", "status", "mimeType", "byteSize", "contentSha256", "createdAt", "aiGenerated", "provenance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "licenseUseId": { "type": "string", "format": "uuid" }, "usageLedgerId": { "type": "string", "format": "uuid", "description": "026 usage_ledger entry charged for this generation (one per licensed use)." }, "licenseId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ], "description": "FAILED records are final for their idempotencyKey; no refund." }, "mimeType": { "type": "string", "nullable": true }, "byteSize": { "type": "integer", "nullable": true }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "aiGenerated": { "type": "boolean", "enum": [ true ] }, "provenance": { "type": "object", "additionalProperties": false, "required": [ "model", "generatedAt" ], "properties": { "model": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" } } } } }, "GenerationResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/Generation" }, "requestId": { "type": "string", "format": "uuid" } } }, "GenerationRecord": { "allOf": [ { "$ref": "#/components/schemas/Generation" }, { "type": "object", "properties": { "errorCode": { "type": "string", "description": "FAILED only." }, "errorMessage": { "type": "string", "nullable": true, "maxLength": 500, "description": "FAILED only; short public message." } } } ] }, "GenerationRecordResponse": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "$ref": "#/components/schemas/GenerationRecord" }, "requestId": { "type": "string", "format": "uuid" } } }, "GenerationPageResponse": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationRecord" } }, "nextCursor": { "type": "string", "nullable": true } } }, "requestId": { "type": "string", "format": "uuid" } } }, "GenerationNotAvailableError": { "description": "409: the generation record is FAILED and has no content.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "GENERATION_NOT_AVAILABLE" ] } } } ] }, "ContentGoneError": { "description": "410: the stored generation file no longer exists.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CONTENT_GONE" ] } } } ] } } }, "tags": [ { "name": "generations", "description": "AI generation records: create (debits one licensed use, no refund on failure) and API Key reads." }, { "name": "usage-terms" } ] }