neurall-io Templates API

openapi: 3.2.0
info:
  title: Neurall API (v3) Templates API
  version: 1.0.0
  description: 'The public v3 surface: /v3/generations for async generations that produce a content asset, /v3/voices for the voice catalog and your own cloned voices, plus file uploads, per-feature pricing, read-only templates, and signed webhooks. Authenticate every call with an API key in the Authorization header. This document is machine-readable at https://api.neurall.io/v3/openapi.json (import it into Postman, or generate a client).'
servers:
- url: https://api.neurall.io
tags:
- name: Templates
  description: 'Ready-made styles per feature: previews plus the prompt behind each one (v3)'
paths:
  /v3/templates:
    get:
      summary: List Templates
      description: 'Published ready-made templates for a feature. Each template carries one or more previews: a thumbnail image, plus a preview video when the feature produces video (e.g. video/logo-reveal). Preview URLs are presigned and expire after ~6 hours. To use a template, resolve its preview id via GET /v3/templates/{previewId} and submit the returned prompt as `args.prompt` in POST /v3/generations.'
      security:
      - ApiKeyAuth: []
      tags:
      - Templates
      parameters:
      - name: feature
        in: query
        required: false
        description: 'Feature key to list templates for (default image/self-portrait). Canonical ''<kind>/<name>'' spellings and the legacy flat spellings are both accepted.

          '
        schema:
          type: string
      - name: category
        in: query
        required: false
        description: 'Only templates in this category. Which categories exist depends on the feature, e.g. video/logo-reveal splits into ''motion'' (intro) and ''outro''.

          '
        schema:
          type: string
      - name: title
        in: query
        required: false
        description: 'Only templates with these exact titles. May REPEAT (?title=Ember+Rush&title=Smoke+Part) to pick a named set without listing a whole library.

          '
        schema:
          type: array
          items:
            type: string
      - name: perCategory
        in: query
        required: false
        description: 'At most N templates of EACH category, rather than the first N rows overall. Rows come back in creation order, so a plain limit on a mixed library returns N of whatever was seeded first and never reaches the other categories. Capped at 50.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - name: limit
        in: query
        required: false
        description: 'Cap the number of templates returned. Useful when a few examples are enough: a full library can be hundreds of rows, each carrying presigned preview URLs. Capped at 500.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 500
      responses:
        '200':
          description: The feature's published templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/Template'
        '401':
          description: Unauthorized
      operationId: getV3Templates
      x-operation-id-source: derived
  /v3/templates/{previewId}:
    get:
      summary: Get Template Prompt
      description: Resolves a preview id from the templates listing to its generation prompt, the exact string to send as `args.prompt` in POST /v3/generations.
      security:
      - ApiKeyAuth: []
      tags:
      - Templates
      parameters:
      - name: previewId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The preview's prompt and its template context
          content:
            application/json:
              schema:
                type: object
                properties:
                  preview:
                    type: object
                    properties:
                      id:
                        type: string
                      templateId:
                        type: string
                      title:
                        type: string
                      feature:
                        type: string
                      gender:
                        type: string
                      prompt:
                        type: string
                        description: Ready to send as `args.prompt` in POST /v3/generations
        '401':
          description: Unauthorized
        '404':
          description: Preview not found
      operationId: getV3TemplatesByPreviewId
      x-operation-id-source: derived
components:
  schemas:
    Template:
      type: object
      description: 'A published ready-made style. Pick one of its previews, resolve the preview id to a prompt via GET /v3/templates/{previewId}, and submit that prompt as `args.prompt` in POST /v3/generations.

        '
      properties:
        id:
          type: string
        title:
          type: string
        category:
          type: string
        feature:
          type: string
          description: Canonical feature key the template belongs to
        previews:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: 'Preview id: pass it to GET /v3/templates/{previewId} to get the prompt'
              gender:
                type: string
                description: Reference gender of the example ('any' for non-person features)
              image:
                type: string
                description: Thumbnail image URL (presigned, expires after ~6 hours)
              video:
                type: string
                description: Preview video URL, present for video features (presigned, expires after ~6 hours)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization