diff --git a/public/.well-known/openapi.yaml b/public/.well-known/openapi.yaml index 61f50a5..f888b53 100644 --- a/public/.well-known/openapi.yaml +++ b/public/.well-known/openapi.yaml @@ -37,6 +37,14 @@ info: All `/v1/vidsheet/` endpoints require an active GEN credit balance. If your organization has no usable credits, requests return `422` with error code `usable_gen_credit_required`. + Credits can be funded with x402 by calling `POST /v1/x402_credit_purchase` + with `workspace_id` plus `amount_usd` or `credits`. If `network` is omitted, + GEN returns every configured payment option in `payment_methods` and + `payment_required.accepts`; show the Sui, Solana, and Base options to the + user or calling agent and sign one selected accept entry. Workspace funding + wallets are backend settlement infrastructure; the user-facing payment + choices are the returned payment methods. + version: 1.0.0 contact: name: GEN Support @@ -123,6 +131,13 @@ tags: `https://agent.gen.pro/v1`. Each scheduled run is gated by available credits: a job remains configured if credits run out and resumes when they return. + - name: Credits + description: | + Read credit balance, transaction history, and available plans. Read-only. + - name: Operations + description: | + Undo/redo history for a sheet (vidsheet). Read the change-set stack, + then undo or redo the top entry. paths: # ── Discovery ────────────────────────────────────────────── @@ -149,6 +164,115 @@ paths: '401': $ref: '#/components/responses/Unauthorized' + /credit_balance: + get: + operationId: getCreditBalance + x-phase: export + summary: Get credit balance + description: | + Returns the agent's available credit balance. Check this before paid + operations (generate, render, publish) to confirm the workspace has + usable credits. Read-only. + tags: [Credits] + parameters: + - $ref: '#/components/parameters/AgentId' + responses: + '200': + description: Available credit balance for the agent's workspace + content: + application/json: + schema: + $ref: '#/components/schemas/CreditBalance' + example: + available_credit: + generic: 48230.5 + '401': + $ref: '#/components/responses/Unauthorized' + + /credit_transactions: + get: + operationId: listCreditTransactions + x-phase: export + summary: List credit transactions + description: | + Lists credit transactions and usage history for an agent. Useful for + answering "how many credits did I spend this week?". Read-only and + paginated. + tags: [Credits] + parameters: + - $ref: '#/components/parameters/AgentId' + - name: page + in: query + required: false + schema: + type: integer + default: 1 + description: Page number (default 1). + responses: + '200': + description: Paginated list of credit transactions + content: + application/json: + schema: + $ref: '#/components/schemas/CreditTransactionList' + '401': + $ref: '#/components/responses/Unauthorized' + + /credit_plans: + get: + operationId: listCreditPlans + x-phase: export + summary: List credit and subscription plans + description: | + Lists available credit and subscription plans. Use this to show a user + their options before they start a purchase. Read-only. + tags: [Credits] + parameters: + - name: cycle + in: query + required: false + schema: + type: string + enum: [monthly, annual] + default: monthly + description: Billing cycle to filter by (default `monthly`). + responses: + '200': + description: Available credit and subscription plans + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/CreditPlan' + '401': + $ref: '#/components/responses/Unauthorized' + + /user_voice_resources: + get: + operationId: listMyVoices + x-phase: setup + summary: List the agent's own voices + description: | + Lists the agent's own custom/created voices — voices the user has + designed, trained, or cloned — not the shared public catalog. Use + `GET /v1/agents/{agent_id}/voice/library` to include public and + connected-provider voices as well. + tags: [Agent Voice] + parameters: + - $ref: '#/components/parameters/AgentId' + responses: + '200': + description: The agent's custom voices + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/VoiceLibraryItem' + '401': + $ref: '#/components/responses/Unauthorized' + /workspaces: get: operationId: listWorkspaces @@ -168,6 +292,64 @@ paths: '401': $ref: '#/components/responses/Unauthorized' + /x402_credit_purchase: + post: + operationId: createX402CreditPurchase + x-phase: export + summary: Create an x402 credit-purchase quote + description: | + Create a 402 quote to fund workspace credits with USDC over x402. + Pass either `amount_usd` or `credits`; x402 credit purchases are not + limited to fixed credit packs. If `network` is omitted, GEN returns + every configured payment option in `payment_methods` and + `payment_required.accepts` instead of silently choosing one chain. + + Show the Sui, Solana, and Base options to the user or calling agent, + sign one matching `payment_required.accepts[]` entry, then settle/retry + with `PAYMENT-SIGNATURE`, `checkout_session_id`, and the chosen network. + Workspace funding wallets are backend settlement/sweeping + infrastructure; the user-facing choices are the returned payment + methods. + tags: [Organizations] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [workspace_id] + properties: + workspace_id: + type: string + description: Workspace/organization receiving credits. + amount_usd: + type: string + description: Arbitrary USD amount to convert to credits. + example: "1.25" + credits: + type: string + description: Arbitrary credit amount to buy. + example: "100.0" + network: + type: string + enum: [sui, solana, base] + description: Optional selected payment network. Omit to receive all configured options. + responses: + '402': + description: x402 payment required. Sign one returned payment method and settle/retry. + content: + application/json: + schema: + $ref: '#/components/schemas/X402CreditPurchaseQuote' + '401': + $ref: '#/components/responses/Unauthorized' + '422': + description: Missing amount, invalid workspace, or quote failure. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agents: get: operationId: listAgents @@ -1515,6 +1697,168 @@ paths: type: string format: binary + /vidsheet/{sheet_id}/operations: + get: + operationId: listOperations + x-phase: edit + summary: List undoable change sets + description: | + Lists recent undoable change sets for a sheet (the undo/redo history), + newest-first. Set `include_undone=true` to also list already-undone + change sets. Use `GET .../operations/last` when you only need the top + of the undo stack. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + description: Max change sets to return (1-100, default 20). + - name: include_undone + in: query + required: false + schema: + type: boolean + default: false + description: Include already-undone change sets (default false). + responses: + '200': + description: Undoable change sets, newest-first + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetList' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + + /vidsheet/{sheet_id}/operations/last: + get: + operationId: getLastOperation + x-phase: edit + summary: Get the next-to-undo change set + description: | + Returns the single next-to-undo change set for a sheet (what the undo + button would take back), or `{change_set: null}` when the stack is + empty. Cheaper than `GET .../operations` when you only need the top of + the undo stack. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + responses: + '200': + description: The next-to-undo change set, or null + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetEnvelope' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + + /vidsheet/{sheet_id}/operations/undo: + post: + operationId: undoOperation + x-phase: edit + summary: Undo a change set + description: | + Undoes the most recent undoable change set, or a specific one by + `change_set_id`. Returns `nothing_to_undo` (422) when the stack is + empty; `409 undo_conflict` means the sheet changed under you — refresh + (`GET /v1/vidsheet/{sheet_id}`) and retry. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + requestBody: + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + description: Undo this specific change set instead of the most recent undoable one. + responses: + '200': + description: The undone change set and the next undoable one + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetResult' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '409': + description: undo_conflict — the sheet changed under you; refresh and retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: nothing_to_undo — the undo stack is empty. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /vidsheet/{sheet_id}/operations/redo: + post: + operationId: redoOperation + x-phase: edit + summary: Redo a change set + description: | + Redoes the most recently undone change set, or a specific one by + `change_set_id`. Returns `nothing_to_redo` (422) when there is nothing + to redo; `409 redo_conflict` means the sheet changed under you — refresh + (`GET /v1/vidsheet/{sheet_id}`) and retry. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + requestBody: + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + description: Redo this specific change set instead of the most recently undone one. + responses: + '200': + description: The redone change set and the next undoable one + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetResult' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '409': + description: redo_conflict — the sheet changed under you; refresh and retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: nothing_to_redo — there is nothing to redo. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + # ── Automation ───────────────────────────────────────────── /agents/{agent_id}/automation_config: get: @@ -1658,7 +2002,13 @@ paths: enum: [publish_content] data: type: string - description: JSON-stringified object with platform, media_url, description, schedule_type, scheduled_time, media_type, title, thumbnail_url, timezone_offset. + description: >- + JSON-stringified object with platform, media_url, description, schedule_type, + scheduled_time, media_type, title, thumbnail_url, timezone_offset. For multiple + images use media_urls (array; X allows up to 4 per tweet). X (Twitter) also + supports thread (array of {text, media_urls?} segments, posted as a chain) and + reply_to_tweet_id (reply to an existing tweet); both are X-only and ignored by + other platforms. example: user_job_type: publish_content data: '{"platform":"tiktok","media_url":"https://cdn.example.com/video.mp4","description":"Factory price reveal #sourcing","schedule_type":"now","media_type":"VIDEO"}' @@ -4139,6 +4489,116 @@ components: type: string schemas: + X402PaymentMethod: + type: object + required: [network, x402Network, asset, payTo, amountUsd, credits] + properties: + network: + type: string + enum: [sui, solana, base] + description: Human-readable payment rail to show to users and agents. + x402Network: + type: string + description: x402 network identifier used inside `payment_required.accepts`. + examples: ["sui", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "eip155:8453"] + asset: + type: string + example: USDC + payTo: + type: string + description: Treasury payment recipient for this rail. + amountUsd: + type: string + description: USD amount represented by this payment method. + credits: + type: string + description: Credits that will be issued after settlement. + + X402Accept: + type: object + required: [scheme, network, asset, maxAmountRequired, payTo, resource] + properties: + scheme: + type: string + example: exact + network: + type: string + asset: + type: string + example: USDC + maxAmountRequired: + type: string + description: Atomic USDC amount required by this accept entry. + payTo: + type: string + resource: + type: string + example: https://api.gen.pro/v1/x402_credit_purchase + description: + type: string + mimeType: + type: string + example: application/json + extra: + type: object + properties: + checkoutSessionId: { type: integer } + workspaceId: { type: integer } + pricingMode: { type: string, enum: [custom_amount, credit_plan] } + amountUsd: { type: string } + credits: { type: string } + network: { type: string, enum: [sui, solana, base] } + referenceCreditPlanId: { type: integer, nullable: true } + + X402PaymentRequired: + type: object + required: [x402Version, accepts] + properties: + x402Version: + type: integer + example: 2 + error: + type: string + paymentMethods: + type: array + items: + $ref: '#/components/schemas/X402PaymentMethod' + accepts: + type: array + items: + $ref: '#/components/schemas/X402Accept' + + X402CreditPurchaseQuote: + type: object + required: [checkout_session_id, workspace_id, amount_usd, credits, payment_methods, payment_required] + properties: + checkout_session_id: + type: integer + workspace_id: + type: integer + pricing_mode: + type: string + enum: [custom_amount, credit_plan] + reference_credit_plan_id: + type: integer + nullable: true + credit_plan_id: + type: integer + nullable: true + quantity: + type: integer + amount_usd: + type: string + credits: + type: string + payment_methods: + type: array + description: User/agent-facing Sui, Solana, and Base payment options. + items: + $ref: '#/components/schemas/X402PaymentMethod' + payment_required: + $ref: '#/components/schemas/X402PaymentRequired' + SongMixTrack: type: object properties: @@ -5226,6 +5686,96 @@ components: delivery: { $ref: '#/components/schemas/RecurringJobDelivery' } next_run_at: { type: string, format: date-time } + CreditBalance: + type: object + description: Available credit balance for the agent's workspace. + properties: + available_credit: + type: object + properties: + generic: + type: number + format: float + description: Credits available for Auto Content Engine and agent.gen.pro operations. + + CreditTransaction: + type: object + properties: + id: { type: integer } + amount: { type: number, format: float, description: Credit delta — negative for a charge, positive for a refund or grant. } + balance_after: { type: number, format: float } + source_type: { type: string, description: What caused the movement (e.g. UserJob, CreditGrant, Payment). } + description: { type: string } + created_at: { type: string, format: date-time } + + CreditTransactionList: + type: object + properties: + transactions: + type: array + items: { $ref: '#/components/schemas/CreditTransaction' } + page: { type: integer } + total_pages: { type: integer } + + CreditPlan: + type: object + description: | + A credit or subscription plan. Exact prices and credit amounts come from + the API response; they change over time, so read them at runtime rather + than hardcoding. + properties: + id: { type: string } + name: { type: string } + cycle: { type: string, enum: [monthly, annual] } + credits: { type: number, format: float, description: Credits included in the plan (when applicable). } + + ChangeSet: + type: object + description: A single undoable change set on a sheet. + properties: + change_set_id: { type: string } + undone: { type: boolean, description: Whether this change set has already been undone. } + created_at: { type: string, format: date-time } + entries: + type: array + items: + type: object + properties: + op: { type: string, description: The operation that was applied. } + path: { type: string } + + ChangeSetList: + type: object + properties: + change_sets: + type: array + items: { $ref: '#/components/schemas/ChangeSet' } + + ChangeSetEnvelope: + type: object + properties: + change_set: + nullable: true + allOf: [ { $ref: '#/components/schemas/ChangeSet' } ] + description: The next-to-undo change set, or null when the stack is empty. + + ChangeSetResult: + type: object + properties: + change_set_id: { type: string } + undone: + type: array + items: { type: object } + description: Entries taken back (undo) or re-applied (redo). + redone: + type: array + items: { type: object } + description: Entries re-applied (redo only). + next_undoable: + nullable: true + allOf: [ { $ref: '#/components/schemas/ChangeSet' } ] + description: The new top of the undo stack after this operation, or null. + responses: Unauthorized: description: Missing or invalid authentication. diff --git a/public/llms-full.txt b/public/llms-full.txt index 9db45e0..424acb0 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -199,6 +199,13 @@ GET /v1/agents/{agent_id}/voice/library?source={public|user_designed|user_traine } ``` +To list only the voices the user **created** (designed, trained, or cloned — not the public catalog): + +``` +GET /v1/user_voice_resources?agent_id={id} +→ [ { voice_id, name, source, preview_url } ] +``` + ### ElevenLabs integration Users connect their own ElevenLabs API key to unlock their personal voice library and use their own quota. @@ -535,6 +542,23 @@ GET /v1/vidsheet/{id}?agent_id={id}&with_execution_cost=true POST /v1/vidsheet/{id}/clone?agent_id={id} Body: { target_agent_id? } → new engine, optionally under a different agent + +# Undo / redo history (every edit is recorded as a change set) +GET /v1/vidsheet/{id}/operations?agent_id={id}&limit=20&include_undone=false +→ { change_sets: [{ change_set_id, undone, created_at, entries }] } newest-first + +GET /v1/vidsheet/{id}/operations/last?agent_id={id} +→ { change_set: {...} | null } # the next-to-undo entry (cheaper than the full list) + +POST /v1/vidsheet/{id}/operations/undo?agent_id={id} +Body: { change_set_id? } # omit to undo the most recent undoable change set +→ { change_set_id, undone: [...], next_undoable: {...} | null } +Errors: 422 nothing_to_undo (stack empty); 409 undo_conflict (sheet changed — refetch and retry) + +POST /v1/vidsheet/{id}/operations/redo?agent_id={id} +Body: { change_set_id? } +→ { change_set_id, redone: [...], next_undoable: {...} | null } +Errors: 422 nothing_to_redo; 409 redo_conflict (refetch and retry) ``` --- @@ -889,6 +913,22 @@ Once configured, generations POST status updates to your `webhook_url`. Render the final composite, poll to completion, download the MP4, optionally publish to TikTok. +## Check Credit Balance and Usage + +Read-only credit endpoints — all free. Check the balance before a paid operation, audit spend with the transaction history, or list plans before a purchase. + +``` +GET /v1/credit_balance?agent_id={id} +→ { available_credit: { generic: } } + +GET /v1/credit_transactions?agent_id={id}&page=1 +→ paginated list of { id, amount, balance_after, source_type, description, created_at } + # amount is negative for a charge, positive for a refund or grant + +GET /v1/credit_plans?cycle={monthly|annual} +→ [ { id, name, cycle, credits } ] # read prices/amounts at runtime — they change +``` + ## Render the Final Video Render is an async generation — same polling pattern as every other generation. diff --git a/public/llms.txt b/public/llms.txt index 9d0ed6a..27de05b 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -99,6 +99,7 @@ GET /v1/agents/:agent_id/core — read flat agent setup PATCH /v1/agents/:agent_id/core — write any subset GET /v1/agents/:agent_id/voice/library — list voices (filter by source) +GET /v1/user_voice_resources?agent_id= — list voices the user created only POST /v1/agents/:agent_id/voice/integrations/elevenlabs — connect user ElevenLabs key POST /v1/agents/:agent_id/voice/integrations/elevenlabs/test — validate without saving DELETE /v1/agents/:agent_id/voice/integrations/elevenlabs — disconnect @@ -446,6 +447,12 @@ GET /v1/vidsheet/:id/global_variables?agent_id= POST /v1/vidsheet/:id/import_global_variables?agent_id= (XLSX) GET /v1/vidsheet/global_variables_template (download template) +# Undo / redo history (every edit is a change set) +GET /v1/vidsheet/:id/operations?agent_id=&limit=&include_undone= +GET /v1/vidsheet/:id/operations/last?agent_id= +POST /v1/vidsheet/:id/operations/undo?agent_id= Body: { change_set_id? } +POST /v1/vidsheet/:id/operations/redo?agent_id= Body: { change_set_id? } + # Content Resources & Assets GET /v1/content_resources?agent_id=&type=&page= POST /v1/content_resources?agent_id= (multipart) @@ -554,6 +561,9 @@ curl "https://api.gen.pro/v1/user_jobs/138860?agent_id=$AGENT_ID" \ ### Step 5 endpoints ``` +GET /v1/credit_balance?agent_id= — read available credits (free) +GET /v1/credit_transactions?agent_id=&page= — usage history (free) +GET /v1/credit_plans?cycle={monthly|annual} — plans to buy (free) POST /v1/vidsheet/:id/cells/:cell_id/render?agent_id= — kick off render GET /v1/generations/:id — poll render POST /v1/user_jobs?agent_id= (publish_content) — publish now / schedule diff --git a/public/openapi.yaml b/public/openapi.yaml index ac4757f..f888b53 100644 --- a/public/openapi.yaml +++ b/public/openapi.yaml @@ -131,6 +131,13 @@ tags: `https://agent.gen.pro/v1`. Each scheduled run is gated by available credits: a job remains configured if credits run out and resumes when they return. + - name: Credits + description: | + Read credit balance, transaction history, and available plans. Read-only. + - name: Operations + description: | + Undo/redo history for a sheet (vidsheet). Read the change-set stack, + then undo or redo the top entry. paths: # ── Discovery ────────────────────────────────────────────── @@ -157,6 +164,115 @@ paths: '401': $ref: '#/components/responses/Unauthorized' + /credit_balance: + get: + operationId: getCreditBalance + x-phase: export + summary: Get credit balance + description: | + Returns the agent's available credit balance. Check this before paid + operations (generate, render, publish) to confirm the workspace has + usable credits. Read-only. + tags: [Credits] + parameters: + - $ref: '#/components/parameters/AgentId' + responses: + '200': + description: Available credit balance for the agent's workspace + content: + application/json: + schema: + $ref: '#/components/schemas/CreditBalance' + example: + available_credit: + generic: 48230.5 + '401': + $ref: '#/components/responses/Unauthorized' + + /credit_transactions: + get: + operationId: listCreditTransactions + x-phase: export + summary: List credit transactions + description: | + Lists credit transactions and usage history for an agent. Useful for + answering "how many credits did I spend this week?". Read-only and + paginated. + tags: [Credits] + parameters: + - $ref: '#/components/parameters/AgentId' + - name: page + in: query + required: false + schema: + type: integer + default: 1 + description: Page number (default 1). + responses: + '200': + description: Paginated list of credit transactions + content: + application/json: + schema: + $ref: '#/components/schemas/CreditTransactionList' + '401': + $ref: '#/components/responses/Unauthorized' + + /credit_plans: + get: + operationId: listCreditPlans + x-phase: export + summary: List credit and subscription plans + description: | + Lists available credit and subscription plans. Use this to show a user + their options before they start a purchase. Read-only. + tags: [Credits] + parameters: + - name: cycle + in: query + required: false + schema: + type: string + enum: [monthly, annual] + default: monthly + description: Billing cycle to filter by (default `monthly`). + responses: + '200': + description: Available credit and subscription plans + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/CreditPlan' + '401': + $ref: '#/components/responses/Unauthorized' + + /user_voice_resources: + get: + operationId: listMyVoices + x-phase: setup + summary: List the agent's own voices + description: | + Lists the agent's own custom/created voices — voices the user has + designed, trained, or cloned — not the shared public catalog. Use + `GET /v1/agents/{agent_id}/voice/library` to include public and + connected-provider voices as well. + tags: [Agent Voice] + parameters: + - $ref: '#/components/parameters/AgentId' + responses: + '200': + description: The agent's custom voices + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/VoiceLibraryItem' + '401': + $ref: '#/components/responses/Unauthorized' + /workspaces: get: operationId: listWorkspaces @@ -1581,6 +1697,168 @@ paths: type: string format: binary + /vidsheet/{sheet_id}/operations: + get: + operationId: listOperations + x-phase: edit + summary: List undoable change sets + description: | + Lists recent undoable change sets for a sheet (the undo/redo history), + newest-first. Set `include_undone=true` to also list already-undone + change sets. Use `GET .../operations/last` when you only need the top + of the undo stack. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + description: Max change sets to return (1-100, default 20). + - name: include_undone + in: query + required: false + schema: + type: boolean + default: false + description: Include already-undone change sets (default false). + responses: + '200': + description: Undoable change sets, newest-first + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetList' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + + /vidsheet/{sheet_id}/operations/last: + get: + operationId: getLastOperation + x-phase: edit + summary: Get the next-to-undo change set + description: | + Returns the single next-to-undo change set for a sheet (what the undo + button would take back), or `{change_set: null}` when the stack is + empty. Cheaper than `GET .../operations` when you only need the top of + the undo stack. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + responses: + '200': + description: The next-to-undo change set, or null + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetEnvelope' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + + /vidsheet/{sheet_id}/operations/undo: + post: + operationId: undoOperation + x-phase: edit + summary: Undo a change set + description: | + Undoes the most recent undoable change set, or a specific one by + `change_set_id`. Returns `nothing_to_undo` (422) when the stack is + empty; `409 undo_conflict` means the sheet changed under you — refresh + (`GET /v1/vidsheet/{sheet_id}`) and retry. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + requestBody: + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + description: Undo this specific change set instead of the most recent undoable one. + responses: + '200': + description: The undone change set and the next undoable one + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetResult' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '409': + description: undo_conflict — the sheet changed under you; refresh and retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: nothing_to_undo — the undo stack is empty. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /vidsheet/{sheet_id}/operations/redo: + post: + operationId: redoOperation + x-phase: edit + summary: Redo a change set + description: | + Redoes the most recently undone change set, or a specific one by + `change_set_id`. Returns `nothing_to_redo` (422) when there is nothing + to redo; `409 redo_conflict` means the sheet changed under you — refresh + (`GET /v1/vidsheet/{sheet_id}`) and retry. + tags: [Operations] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + requestBody: + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + description: Redo this specific change set instead of the most recently undone one. + responses: + '200': + description: The redone change set and the next undoable one + content: + application/json: + schema: + $ref: '#/components/schemas/ChangeSetResult' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '409': + description: redo_conflict — the sheet changed under you; refresh and retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: nothing_to_redo — there is nothing to redo. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + # ── Automation ───────────────────────────────────────────── /agents/{agent_id}/automation_config: get: @@ -5408,6 +5686,96 @@ components: delivery: { $ref: '#/components/schemas/RecurringJobDelivery' } next_run_at: { type: string, format: date-time } + CreditBalance: + type: object + description: Available credit balance for the agent's workspace. + properties: + available_credit: + type: object + properties: + generic: + type: number + format: float + description: Credits available for Auto Content Engine and agent.gen.pro operations. + + CreditTransaction: + type: object + properties: + id: { type: integer } + amount: { type: number, format: float, description: Credit delta — negative for a charge, positive for a refund or grant. } + balance_after: { type: number, format: float } + source_type: { type: string, description: What caused the movement (e.g. UserJob, CreditGrant, Payment). } + description: { type: string } + created_at: { type: string, format: date-time } + + CreditTransactionList: + type: object + properties: + transactions: + type: array + items: { $ref: '#/components/schemas/CreditTransaction' } + page: { type: integer } + total_pages: { type: integer } + + CreditPlan: + type: object + description: | + A credit or subscription plan. Exact prices and credit amounts come from + the API response; they change over time, so read them at runtime rather + than hardcoding. + properties: + id: { type: string } + name: { type: string } + cycle: { type: string, enum: [monthly, annual] } + credits: { type: number, format: float, description: Credits included in the plan (when applicable). } + + ChangeSet: + type: object + description: A single undoable change set on a sheet. + properties: + change_set_id: { type: string } + undone: { type: boolean, description: Whether this change set has already been undone. } + created_at: { type: string, format: date-time } + entries: + type: array + items: + type: object + properties: + op: { type: string, description: The operation that was applied. } + path: { type: string } + + ChangeSetList: + type: object + properties: + change_sets: + type: array + items: { $ref: '#/components/schemas/ChangeSet' } + + ChangeSetEnvelope: + type: object + properties: + change_set: + nullable: true + allOf: [ { $ref: '#/components/schemas/ChangeSet' } ] + description: The next-to-undo change set, or null when the stack is empty. + + ChangeSetResult: + type: object + properties: + change_set_id: { type: string } + undone: + type: array + items: { type: object } + description: Entries taken back (undo) or re-applied (redo). + redone: + type: array + items: { type: object } + description: Entries re-applied (redo only). + next_undoable: + nullable: true + allOf: [ { $ref: '#/components/schemas/ChangeSet' } ] + description: The new top of the undo stack after this operation, or null. + responses: Unauthorized: description: Missing or invalid authentication. diff --git a/src/content/docs/reference/agent-voice.mdx b/src/content/docs/reference/agent-voice.mdx index bcc6912..f97a7ef 100644 --- a/src/content/docs/reference/agent-voice.mdx +++ b/src/content/docs/reference/agent-voice.mdx @@ -35,6 +35,19 @@ GET /v1/agents/{agent_id}/voice/library The `user_elevenlabs` source only appears when the agent has a connected ElevenLabs API key (see below). +### List the agent's own voices + +``` +GET /v1/user_voice_resources?agent_id={agent_id} +``` + +Returns only the voices the user **created** — designed, trained, or cloned — not the shared public catalog. Use `GET /v1/agents/{agent_id}/voice/library` (above) when you want the public and connected-provider voices as well. + +```bash +curl "https://api.gen.pro/v1/user_voice_resources?agent_id=$AGENT_ID" \ + -H "X-API-Key: $GEN_API_KEY" +``` + ## ElevenLabs integration Users connect their own ElevenLabs API key to unlock their personal voice library and use their own usage quota. The key is validated against ElevenLabs `/v1/user` before being saved on the agent record. diff --git a/src/content/docs/reference/endpoints-index.mdx b/src/content/docs/reference/endpoints-index.mdx index 3f1da42..7c74d77 100644 --- a/src/content/docs/reference/endpoints-index.mdx +++ b/src/content/docs/reference/endpoints-index.mdx @@ -55,6 +55,7 @@ All endpoints authenticate with `X-API-Key: ` or `Authorization: Beare | Method | Path | Phase | |--------|------|-------| | GET | /v1/agents/:agent_id/voice/library | setup | +| GET | /v1/user_voice_resources?agent_id= | setup | | GET | /v1/agents/:agent_id/voice/integrations/elevenlabs | setup | | POST | /v1/agents/:agent_id/voice/integrations/elevenlabs | setup | | POST | /v1/agents/:agent_id/voice/integrations/elevenlabs/test | setup | @@ -129,6 +130,10 @@ All endpoints authenticate with `X-API-Key: ` or `Authorization: Beare | POST | /v1/vidsheet | convert | | GET | /v1/vidsheet/:id | convert | | POST | /v1/vidsheet/:id/clone | convert | +| GET | /v1/vidsheet/:id/operations | edit | +| GET | /v1/vidsheet/:id/operations/last | edit | +| POST | /v1/vidsheet/:id/operations/undo | edit | +| POST | /v1/vidsheet/:id/operations/redo | edit | ## Rows @@ -233,3 +238,11 @@ All endpoints authenticate with `X-API-Key: ` or `Authorization: Beare | PATCH | /v1/agents/:agent_id/automation_config | edit | | POST | /v1/agents/:agent_id/automation_config/test_webhook | edit | | POST | /v1/agents/:agent_id/automation_config/test_callback | edit | + +## Credits + +| Method | Path | Phase | +|--------|------|-------| +| GET | /v1/credit_balance?agent_id= | export | +| GET | /v1/credit_transactions?agent_id= | export | +| GET | /v1/credit_plans | export | diff --git a/src/content/docs/reference/sheets.mdx b/src/content/docs/reference/sheets.mdx index ae18eb6..24b7394 100644 --- a/src/content/docs/reference/sheets.mdx +++ b/src/content/docs/reference/sheets.mdx @@ -174,3 +174,65 @@ curl -X POST "https://api.gen.pro/v1/vidsheet/101/clone?agent_id=42" \ |--------|------------|-------------| | `404` | `not_found` | Engine not found or agent does not have access. | | `422` | `validation_error` | Target agent not accessible or insufficient credits. | + +## Undo / redo history + +Every edit to a sheet (cell updates, layer changes, column moves, etc.) is recorded as a **change set**. You can read the stack and undo or redo its top entry. This mirrors the undo/redo button in the GEN UI. + +### List change sets + +``` +GET /v1/vidsheet/{sheet_id}/operations?agent_id={agent_id} +``` + +**Query params:** +- `limit` (optional) — max change sets to return, 1–100 (default 20) +- `include_undone` (optional) — include already-undone change sets (default `false`) + +Returns `{ change_sets: [...] }` newest-first. + +### Peek at the next-to-undo entry + +``` +GET /v1/vidsheet/{sheet_id}/operations/last?agent_id={agent_id} +``` + +Returns just the single change set the undo button would take back — `{ change_set: ... }`, or `{ change_set: null }` when the stack is empty. Cheaper than the full list when you only need the top of the stack. + +### Undo + +``` +POST /v1/vidsheet/{sheet_id}/operations/undo?agent_id={agent_id} +``` + +Undoes the most recent undoable change set. Send a body with a `change_set_id` to undo a specific change set instead of the most recent one. + +```bash +curl -X POST "https://api.gen.pro/v1/vidsheet/101/operations/undo?agent_id=42" \ + -H "X-API-Key: your-api-key" +``` + +Returns `{ change_set_id, undone: [...], next_undoable: {...} | null }`. + +### Redo + +``` +POST /v1/vidsheet/{sheet_id}/operations/redo?agent_id={agent_id} +``` + +Re-applies the most recently undone change set (or a specific one by `change_set_id`). + +```bash +curl -X POST "https://api.gen.pro/v1/vidsheet/101/operations/redo?agent_id=42" \ + -H "X-API-Key: your-api-key" +``` + +Returns `{ change_set_id, redone: [...], next_undoable: {...} | null }`. + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `404` | `not_found` | Sheet not found or agent does not have access. | +| `409` | `undo_conflict` / `redo_conflict` | The sheet changed under you. Re-fetch the sheet (`GET /v1/vidsheet/{sheet_id}`) and retry. | +| `422` | `nothing_to_undo` / `nothing_to_redo` | The relevant stack is empty. | diff --git a/src/content/docs/step-5-export/credits.mdx b/src/content/docs/step-5-export/credits.mdx index 231920d..f59b3db 100644 --- a/src/content/docs/step-5-export/credits.mdx +++ b/src/content/docs/step-5-export/credits.mdx @@ -18,6 +18,51 @@ curl "https://api.gen.pro/v1/organizations/$ORG_ID" \ Response includes `available_credit: { generic, aura }`. The `generic` bucket covers all Auto Content Engine + agent.gen.pro operations; the `aura` bucket is for connected-social features and isn't consumed by the API surface. +## Check your balance and usage + +Three read-only endpoints tell you how many credits you have, where they went, and what plans are available. All are free. + +### Balance + +Check the agent's available credits before a paid operation (generate, render, publish). + +```bash +curl "https://api.gen.pro/v1/credit_balance?agent_id=$AGENT_ID" \ + -H "X-API-Key: $GEN_API_KEY" +``` + +```json +{ + "available_credit": { + "generic": 48230.5 + } +} +``` + +The `generic` bucket covers Auto Content Engine and agent.gen.pro operations. + +### Usage history + +List credit transactions to answer questions like "how many credits did I spend this week?". Negative `amount` values are charges; positive values are refunds or grants. Paginated. + +```bash +curl "https://api.gen.pro/v1/credit_transactions?agent_id=$AGENT_ID&page=1" \ + -H "X-API-Key: $GEN_API_KEY" +``` + +### Available plans + +List the credit and subscription plans a user can buy. Filter by billing cycle with the `cycle` query parameter (`monthly`, the default, or `annual`). Use this to show options before starting a purchase. + +```bash +curl "https://api.gen.pro/v1/credit_plans?cycle=monthly" \ + -H "X-API-Key: $GEN_API_KEY" +``` + + + ## Buying credits with x402 Credit purchases can be funded with Stripe or with x402. x402 purchases are arbitrary amount: pass either `amount_usd` or `credits`, and GEN returns a `402 Payment Required` quote.