{ "openapi": "3.1.0", "info": { "title": "Voz Studio Agent API", "version": "0.2.0", "description": "Brazilian narration and word timings. Prepaid 30-day plans via Pix. No automatic debit, renewal or MP4 rendering." }, "servers": [ { "url": "/" } ], "security": [ { "ApiKey": [] } ], "paths": { "/v1/accounts": { "post": { "operationId": "createAccount", "summary": "Create an automation account; save the returned API key immediately. No email identity is claimed.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "api_key": { "type": "string" }, "save_key_now": { "const": true } } } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ] } } } } } }, "/v1/plans": { "get": { "operationId": "listPlans", "summary": "Get current plan, price and provider readiness.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "ready": { "type": "boolean" } } } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/me": { "get": { "operationId": "getAccount", "summary": "Inspect quota and expiration before submitting scripts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/purchases": { "get": { "operationId": "listPurchases", "summary": "Recover the latest 30 purchase records after a lost response.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } } } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPurchase", "summary": "Create a Pix charge within the explicit spending cap. This does not pay it.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "enum": [ "creator_30" ] }, "max_amount_cents": { "type": "integer", "minimum": 100 } }, "required": [ "plan_id", "max_amount_cents" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]+$" } } ] } }, "/v1/purchases/{id}": { "get": { "operationId": "getPurchase", "summary": "Check payment with AbacatePay; a paid purchase grants quota exactly once.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/generations": { "get": { "operationId": "listGenerations", "summary": "List generation jobs, 30 per page. Store IDs and polling URLs.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "generations": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "page": { "type": "integer" }, "next_page": { "type": [ "integer", "null" ] } } } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ] }, "post": { "operationId": "createGeneration", "summary": "Reserve quota and queue a script. Same key and text returns the existing job.", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 3000, "description": "PT-BR. Up to 40 spoken segments. *word* preserves emphasis in palavras.json." } }, "required": [ "text" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]+$" } } ] } }, "/v1/generations/{id}": { "get": { "operationId": "getGeneration", "summary": "Poll at intervals of at least 5 seconds.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/generations/{id}/retry": { "post": { "operationId": "retryGeneration", "summary": "Retry a failed job up to three total attempts; quota is reserved again, never charged twice for one run.", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/generations/{id}/files/{file}": { "get": { "operationId": "downloadFile", "summary": "Download an artifact belonging to this account.", "responses": { "200": { "description": "Private file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Structured error. 402 means a plan or quota is required; no automatic charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "voz.wav", "palavras.json", "info.json", "captions.srt", "captions.vtt", "timestamps.json", "audio.wav", "narracao.zip" ] } } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "API key returned only at account creation. Store in a secret manager." } }, "schemas": { "Account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "expires_at": { "type": [ "integer", "null" ], "description": "Unix seconds" }, "characters_remaining": { "type": "integer" }, "generations_remaining": { "type": "integer" }, "attempts_remaining": { "type": "integer" }, "email": { "type": [ "string", "null" ], "description": "Verified recovery email, when linked in the studio." } } }, "Plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "amount_cents": { "type": "integer" }, "currency": { "const": "BRL" }, "days": { "type": "integer" }, "generations": { "type": "integer" }, "characters": { "type": "integer" }, "attempts": { "type": "integer" }, "max_characters_per_script": { "type": "integer" }, "target_videos": { "type": "integer" }, "target_video_minutes": { "type": "integer" }, "duration_is_estimate": { "const": true }, "auto_renew": { "const": false }, "price_status": { "const": "beta" }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "PIX", "CARD" ] }, "description": "Available payment methods; CARD appears only after checkout is configured." }, "card_installments": { "type": "integer", "const": 1 } } }, "Pix": { "type": "object", "properties": { "id": { "type": "string" }, "brCode": { "type": "string" }, "brCodeBase64": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "Purchase": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "pending", "paid", "expired", "creation_failed" ] }, "amount": { "type": "integer" }, "plan": { "$ref": "#/components/schemas/Plan" }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/Pix" }, { "$ref": "#/components/schemas/HostedCheckout" }, { "type": "null" } ] } } }, "Generation": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "text": { "type": "string" }, "attempts": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "status_url": { "type": "string" }, "retry_url": { "type": "string" }, "files": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Relative paths; every download requires the same Bearer API key." }, "stage": { "type": [ "string", "null" ], "enum": [ "synthesizing", "aligning", "packaging", null ], "description": "Current processing stage; use status to determine completion." } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "payment_action": { "type": "object" } } }, "HostedCheckout": { "type": "object", "required": [ "id", "kind", "url" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "const": "checkout" }, "url": { "type": "string", "format": "uri", "description": "AbacatePay hosted payment page. The payer must authorize the purchase." } } } } } }