@spicyapi/sdk 0.1.0

package/contracts/openapi.yaml

@@ -0,0 +1,752 @@
+openapi: 3.1.0
+info:
+  title: SpicyAPI Public API
+  version: 1.0.0
+  description: |
+    Contract for the implemented `/api/v1` integration surface.
+
+    Every operation requires a Bearer API key. Every JSON response uses the
+    `{code,msg,data,request_id}` envelope. A successful HTTP response has
+    `code: 200`; asynchronous task success or failure is expressed by
+    `data.state`, not by the envelope code.
+servers:
+  - url: https://api.spicyapi.ai
+    description: Production
+tags:
+  - name: Tasks
+  - name: Models
+  - name: Account
+  - name: Media
+security:
+  - bearerAuth: []
+paths:
+  /api/v1/jobs/createTask:
+    post:
+      tags: [Tasks]
+      operationId: createTask
+      summary: Create an asynchronous generation task
+      description: |
+        Validates the model input, reserves the estimated charge, chooses an
+        available deployment, and creates a task in `queued` state. HTTP 202
+        means the task was accepted; it does not mean generation has completed.
+
+        An `Idempotency-Key` is optional but strongly recommended. For the same
+        account **and the same API key**, repeating a key with the same normalized
+        model, input, callback URL, and mature flag within 24 hours returns the
+        original task and does not reserve funds twice. A sibling API key cannot
+        replay the mapping: it receives `409 Conflict` without the original task
+        ID. Reusing the key with different request semantics also returns
+        `409 Conflict`. Callbacks are optional and are validated against
+        private/loopback destinations before acceptance.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTaskRequest'
+      responses:
+        '202':
+          description: A newly accepted task is returned in `queued` state. A same-key idempotent replay returns the original task in its current state and does not create another hold. The hold is not a charge.
+          headers:
+            Location:
+              description: Relative URL of the task status resource.
+              schema: { type: string }
+            Retry-After: { $ref: '#/components/headers/RetryAfter' }
+            Cache-Control:
+              description: Task submissions contain caller-specific state and must not be cached.
+              schema: { type: string, const: no-store }
+            X-RateLimit-Limit: { $ref: '#/components/headers/RateLimitLimit' }
+            X-RateLimit-Remaining: { $ref: '#/components/headers/RateLimitRemaining' }
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateTaskEnvelope'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '402': { $ref: '#/components/responses/PaymentRequired' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+        '503': { $ref: '#/components/responses/Unavailable' }
+      callbacks:
+        onTaskTerminal:
+          '{$request.body#/callBackUrl}':
+            post:
+              summary: Deliver a terminal task record
+              description: |
+                Sent only when `callBackUrl` was supplied. New integrations use
+                payload version 2, whose body is the same envelope and task
+                record returned by `recordInfo`. Payload version 1 remains a
+                compatibility output and is selected by the version header.
+
+                Verify `X-Webhook-Signature` over
+                `taskId.timestamp.sha256(raw_body)` with HMAC-SHA256 and the
+                account webhook key. Select `taskId` from top-level `task_id`
+                for payload v1 and from `data.taskId` for payload v2, then
+                compare the Base64-encoded result in constant time.
+                Reject stale timestamps. A delivery may be retried and receivers
+                must be idempotent; in v2, `request_id` is the stable delivery ID.
+              parameters:
+                - name: X-Webhook-Timestamp
+                  in: header
+                  required: true
+                  schema: { type: string, pattern: '^[0-9]+$' }
+                  description: Unix timestamp used by the signature.
+                - name: X-Webhook-Signature
+                  in: header
+                  required: true
+                  schema: { type: string }
+                  description: Base64-encoded HMAC-SHA256 signature.
+                - name: X-Webhook-Payload-Version
+                  in: header
+                  required: true
+                  schema: { type: integer, enum: [1, 2] }
+              requestBody:
+                required: true
+                content:
+                  application/json:
+                    schema:
+                      oneOf:
+                        - $ref: '#/components/schemas/TaskRecordEnvelope'
+                        - $ref: '#/components/schemas/LegacyWebhookPayload'
+              responses:
+                '200':
+                  description: Any 2xx response acknowledges delivery.
+  /api/v1/jobs/recordInfo:
+    get:
+      tags: [Tasks]
+      operationId: recordInfo
+      summary: Get a task created by the authenticated API key
+      parameters:
+        - name: taskId
+          in: query
+          required: true
+          schema: { type: string, minLength: 1 }
+      responses:
+        '200':
+          description: Current task record. Terminal and non-terminal states share this shape.
+          headers:
+            Cache-Control:
+              description: Task state is caller-specific and changes asynchronously.
+              schema: { type: string, const: no-store }
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaskRecordEnvelope'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: Task does not exist or belongs to another account or API key; these cases are indistinguishable.
+          headers:
+            Cache-Control:
+              schema: { type: string, const: no-store }
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/jobs/retry:
+    post:
+      tags: [Tasks]
+      operationId: retryTask
+      summary: Create a new task from a failed or expired task
+      description: |
+        The source terminal task is never modified. Current model schema,
+        pricing, permissions, balance, and routing are evaluated again. An
+        optional Idempotency-Key is scoped to the source task and retry action.
+        The source task must have been created by the same API key; unknown,
+        cross-account, and same-account cross-key task IDs all return 404.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/TaskActionRequest' }
+      responses:
+        '200':
+          description: A newly created retry task is returned in `queued` state. An idempotent replay returns that retry task in its current state.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RetryTaskEnvelope' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '402': { $ref: '#/components/responses/PaymentRequired' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+        '503': { $ref: '#/components/responses/Unavailable' }
+  /api/v1/models:
+    get:
+      tags: [Models]
+      operationId: listModels
+      summary: List callable models and account-specific prices
+      description: |
+        Returns all enabled models without pagination. The response is private
+        because prices include the authenticated account's group multiplier.
+        The server sends `Cache-Control: private, max-age=60`.
+      parameters:
+        - name: modality
+          in: query
+          schema: { type: string, enum: [image, video, audio, text] }
+        - name: provider
+          in: query
+          schema: { type: string }
+        - name: task
+          in: query
+          schema: { type: string }
+          description: Exact supported task, for example `text-to-image`.
+        - name: search
+          in: query
+          schema: { type: string, maxLength: 128 }
+        - name: includeSchema
+          in: query
+          schema:
+            oneOf:
+              - { type: boolean }
+              - { type: integer, enum: [0, 1] }
+          description: Include each model's input JSON Schema when `true` or `1`.
+        - name: includeExamples
+          in: query
+          schema:
+            oneOf:
+              - { type: boolean }
+              - { type: integer, enum: [0, 1] }
+          description: Include validated example inputs when `true` or `1`.
+      responses:
+        '200':
+          description: Model list.
+          headers:
+            Cache-Control:
+              schema: { type: string, const: 'private, max-age=60' }
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ModelListEnvelope'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/models/{model}:
+    get:
+      tags: [Models]
+      operationId: getModel
+      summary: Get one model, including its input JSON Schema
+      description: |
+        `model` is the exact value used by `createTask.model` and may contain
+        slashes. URL-encode embedded slashes when using clients that treat path
+        parameters as one segment (for example `bytedance%2Fseedance-2-fast`).
+      parameters:
+        - name: model
+          in: path
+          required: true
+          allowReserved: true
+          schema: { type: string, minLength: 1 }
+      responses:
+        '200':
+          description: Complete model record.
+          headers:
+            Cache-Control:
+              schema: { type: string, const: 'private, max-age=60' }
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ModelEnvelope'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/chat/credit:
+    get:
+      tags: [Account]
+      operationId: getCreditBalance
+      summary: Get the account balance
+      responses:
+        '200':
+          description: Available, held, and total balance in USD decimal strings.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BalanceEnvelope'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/common/upload-url:
+    post:
+      tags: [Media]
+      operationId: createUploadUrl
+      summary: Create a presigned image upload ticket
+      description: |
+        The server generates the object key. Upload the exact declared number of
+        bytes with PUT and copy every returned header. Supported media types are
+        JPEG, PNG, WebP, and GIF; the default maximum is 10 MiB. After PUT,
+        call the file commit endpoint and use its spicy:// URI in task input.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UploadURLRequest'
+      responses:
+        '200':
+          description: Presigned upload ticket.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UploadURLEnvelope'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/files/{fileId}/commit:
+    post:
+      tags: [Media]
+      operationId: commitUploadedFile
+      summary: Commit a completed direct upload
+      description: |
+        Compares the stored byte count and media type with the ticket, checks
+        the image signature, computes SHA-256, and copies the temporary object
+        to an immutable private key. Only the returned spicy:// URI can be used
+        in task input. Repeating a successful commit is idempotent.
+      parameters:
+        - name: fileId
+          in: path
+          required: true
+          schema: { type: string, pattern: '^fil_' }
+      responses:
+        '200':
+          description: Ready tenant-scoped file reference.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FileCommitEnvelope' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/common/download-url:
+    post:
+      tags: [Media]
+      operationId: createDownloadUrl
+      summary: Create a short-lived task output download URL
+      description: |
+        The server verifies both task ownership and that the requested key is an
+        output of that task. Leave `key` empty to select the first output.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DownloadURLRequest'
+      responses:
+        '200':
+          description: Short-lived download ticket.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadURLEnvelope'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: 'sk-spicy-<48 lowercase hex characters>'
+      description: 'Send `Authorization: Bearer sk-spicy-...`. Keep keys server-side.'
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: Stable key for one logical task submission; retained for 24 hours per account and bound to both the submitting API key and normalized request fingerprint. A sibling key receives 409 without the original task ID.
+      schema: { type: string, minLength: 1, maxLength: 128 }
+  headers:
+    RateLimitLimit:
+      description: Capacity of the active account-level rate-limit window.
+      schema: { type: integer }
+    RateLimitRemaining:
+      description: Remaining requests in the active window.
+      schema: { type: integer }
+    RetryAfter:
+      description: Seconds to wait before retrying.
+      schema: { type: integer, minimum: 1 }
+  responses:
+    BadRequest:
+      description: Invalid JSON, query, callback URL, model input, or media declaration.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    Unauthorized:
+      description: Missing, malformed, expired, revoked, or otherwise invalid API key.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    PaymentRequired:
+      description: Insufficient balance (`40201`) or a spend cap was reached (`40202`).
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    Forbidden:
+      description: Account, model, API-key, IP, or region authorization failed.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    NotFound:
+      description: Resource does not exist or is not visible to this account and API key. These cases are intentionally indistinguishable.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    Conflict:
+      description: Idempotency or media-transfer state conflicts with this request.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    PayloadTooLarge:
+      description: Request body exceeds the server's accepted size limit.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    RateLimited:
+      description: Account-level request limit exceeded.
+      headers:
+        X-RateLimit-Limit: { $ref: '#/components/headers/RateLimitLimit' }
+        X-RateLimit-Remaining: { $ref: '#/components/headers/RateLimitRemaining' }
+        Retry-After: { $ref: '#/components/headers/RetryAfter' }
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    ServerError:
+      description: Internal failure. Details are not exposed; report `request_id` to support.
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    Unavailable:
+      description: No usable deployment or effective customer price exists for the selected model (`50301`).
+      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+  schemas:
+    EnvelopeBase:
+      type: object
+      required: [code, msg, request_id]
+      properties:
+        code: { type: integer }
+        msg: { type: string }
+        request_id:
+          type: string
+          description: Correlation identifier. Include it in support requests.
+    ErrorEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          properties:
+            code:
+              type: integer
+              enum: [400, 401, 40201, 40202, 403, 40301, 40302, 40303, 404, 409, 413, 429, 500, 50301]
+            msg: { type: string }
+    CreateTaskRequest:
+      type: object
+      required: [model, input]
+      additionalProperties: false
+      properties:
+        model:
+          type: string
+          minLength: 1
+          description: Exact `model` value from the model catalog.
+        input:
+          type: object
+          description: Validated against the selected model's `inputSchema`.
+          additionalProperties: true
+        callBackUrl:
+          type: string
+          format: uri
+          description: Optional public HTTP(S) endpoint for terminal task delivery.
+        mature:
+          type: boolean
+          default: false
+          description: Optional execution metadata passed through to the selected model. The platform applies no account, API-key, model-capability, channel-capability, or content-preflight gate to this field.
+    CreateTaskResponse:
+      type: object
+      required: [taskId, state, estimatedCost]
+      properties:
+        taskId: { type: string }
+        state:
+          type: string
+          enum: [queued, running, succeeded, failed, canceled, expired]
+          description: "`queued` for a new submission; an idempotent replay reports the original task's current state."
+        estimatedCost:
+          allOf:
+            - $ref: '#/components/schemas/USDString'
+          description: Funds held when the task is accepted and the maximum amount charged for that task. Unused funds are released; provider overage is absorbed by the platform.
+    TaskActionRequest:
+      type: object
+      required: [taskId]
+      additionalProperties: false
+      properties:
+        taskId: { type: string, minLength: 1 }
+    RetryTaskResponse:
+      allOf:
+        - $ref: '#/components/schemas/CreateTaskResponse'
+        - type: object
+          required: [sourceTaskId]
+          properties:
+            sourceTaskId: { type: string }
+    RetryTaskEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/RetryTaskResponse' }
+    CreateTaskEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/CreateTaskResponse' }
+    TaskRecord:
+      type: object
+      required: [taskId, model, state, cost, settled, createdAt]
+      properties:
+        taskId: { type: string }
+        sourceTaskId: { type: string, description: Present when this task was created by explicit retry. }
+        model: { type: string }
+        state:
+          type: string
+          enum: [queued, running, succeeded, failed, canceled, expired]
+        input:
+          description: Normalized model input. Omitted after retention redaction.
+          type: object
+          additionalProperties: true
+        output:
+          description: Normalized model output when available. Omitted after retention redaction.
+          type: object
+          additionalProperties: true
+        errorCode: { type: string }
+        errorMessage: { type: string }
+        cost: { $ref: '#/components/schemas/USDString' }
+        settled:
+          type: boolean
+          description: When false, `cost` is the held estimate. On success the final charge is capped at that hold; unused funds are released. Failed or expired tasks release the hold in full.
+        createdAt: { type: string, format: date-time }
+        completedAt: { type: string, format: date-time }
+    TaskRecordEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/TaskRecord' }
+    LegacyWebhookPayload:
+      type: object
+      deprecated: true
+      description: Version 1 compatibility callback. New integrations must use version 2.
+      required: [task_id, model, state, cost, created_at]
+      properties:
+        task_id: { type: string }
+        model: { type: string }
+        state: { type: string, enum: [queued, running, succeeded, failed, canceled, expired] }
+        output: { type: object, additionalProperties: true }
+        error_code: { type: string }
+        error_message: { type: string }
+        cost: { $ref: '#/components/schemas/USDString' }
+        created_at: { type: string, format: date-time }
+    Balance:
+      type: object
+      required: [available, held, total]
+      properties:
+        available: { $ref: '#/components/schemas/USDString' }
+        held: { $ref: '#/components/schemas/USDString' }
+        total: { $ref: '#/components/schemas/USDString' }
+    BalanceEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/Balance' }
+    APIModelPrice:
+      type: object
+      required: [variant, unit, price, currency]
+      properties:
+        variant:
+          type: string
+          description: Value used by `input.resolution`; empty when the model has one price tier.
+        unit: { type: string, enum: [per_image, per_second, per_request, per_1k_tokens] }
+        price: { $ref: '#/components/schemas/USDString' }
+        currency: { type: string, const: USD }
+    APIModel:
+      type: object
+      required: [model, family, displayName, provider, modality, tasks, async, mature, policyTier, taskTimeoutSeconds, enabled, available, quantityField, pricing, version, availability, badges, relatedModels, updatedAt]
+      properties:
+        model: { type: string }
+        family:
+          type: string
+          description: Stable product-family identifier; endpoint variants are listed in `tasks` and expressed by `inputSchema`.
+        displayName: { type: string }
+        provider: { type: string }
+        modality: { type: string, enum: [image, video, audio, text] }
+        tasks: { type: array, items: { type: string } }
+        async: { type: boolean }
+        mature:
+          type: boolean
+          description: Informational model-creator capability metadata only. It does not participate in routing, authorization, or request rejection.
+        policyTier:
+          type: string
+          enum: [unrestricted, borderline, unspecified]
+          description: Informational model-creator policy metadata only. It does not participate in routing, authorization, or request rejection.
+        taskTimeoutSeconds:
+          type: integer
+          minimum: 1
+          description: Absolute platform execution deadline before timeout/refund; not media output duration.
+        maxOutputDurationSeconds:
+          type: integer
+          minimum: 1
+          description: Maximum `input.duration` accepted by the model schema; omitted when the model has no declared duration maximum.
+        enabled: { type: boolean }
+        available: { type: boolean }
+        quantityField: { type: string }
+        pricing: { type: array, items: { $ref: '#/components/schemas/APIModelPrice' } }
+        startingPrice: { $ref: '#/components/schemas/APIModelPrice' }
+        inputSchema:
+          type: object
+          description: JSON Schema draft 2020-12 used by `createTask.input` validation.
+          additionalProperties: true
+        version:
+          type: string
+          description: Provider/model version label used to detect catalog changes.
+        availability:
+          type: string
+          enum: [planned, available, preview, maintenance]
+        badges:
+          type: array
+          description: Closed capability and licensing vocabulary; clients should ignore unknown future IDs.
+          items:
+            type: string
+            enum: [commercial_use, no_watermark, commercial_restricted, reference_input, audio_output, streaming, fast_tier, high_resolution, long_context, mature_capable, policy_unrestricted, policy_borderline]
+        relatedModels:
+          type: array
+          description: Curated model identifiers suitable for alternatives or workflow steps.
+          items: { type: string }
+        examples:
+          type: array
+          description: Inputs validated against this model's current input schema.
+          items: { $ref: '#/components/schemas/APIModelExample' }
+        updatedAt: { type: string, format: date-time }
+    APIModelExample:
+      type: object
+      required: [id, input, sortWeight]
+      properties:
+        id: { type: string }
+        input: { type: object, additionalProperties: true }
+        sortWeight: { type: integer }
+    APIModelList:
+      type: object
+      required: [total, items]
+      properties:
+        total: { type: integer, minimum: 0 }
+        items: { type: array, items: { $ref: '#/components/schemas/APIModel' } }
+    ModelEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/APIModel' }
+    ModelListEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/APIModelList' }
+    UploadURLRequest:
+      type: object
+      required: [contentType, bytes]
+      additionalProperties: false
+      properties:
+        contentType: { type: string, enum: [image/jpeg, image/png, image/webp, image/gif] }
+        bytes: { type: integer, minimum: 1, maximum: 10485760 }
+    UploadURLResponse:
+      type: object
+      required: [fileId, key, uploadUrl, method, headers, expiresAt, maxBytes]
+      properties:
+        fileId: { type: string, pattern: '^fil_' }
+        key: { type: string, pattern: '^spicy://f/fil_', description: Compatibility alias for the final URI; unusable until commit succeeds. }
+        uploadUrl: { type: string, format: uri }
+        method: { type: string, const: PUT }
+        headers: { type: object, additionalProperties: { type: string } }
+        expiresAt: { type: string, format: date-time }
+        maxBytes: { type: integer, minimum: 1 }
+    UploadURLEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/UploadURLResponse' }
+    FileCommitResponse:
+      type: object
+      required: [fileId, status, bytes, contentType, sha256, uri, expiresAt]
+      properties:
+        fileId: { type: string, pattern: '^fil_' }
+        status: { type: string, const: ready }
+        bytes: { type: integer, minimum: 1 }
+        contentType: { type: string, enum: [image/jpeg, image/png, image/webp, image/gif] }
+        sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
+        uri: { type: string, pattern: '^spicy://f/fil_' }
+        expiresAt: { type: string, format: date-time }
+    FileCommitEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/FileCommitResponse' }
+    DownloadURLRequest:
+      type: object
+      required: [taskId]
+      additionalProperties: false
+      properties:
+        taskId: { type: string, minLength: 1 }
+        key: { type: string, description: Optional output key; empty selects the first output. }
+    DownloadURLResponse:
+      type: object
+      required: [key, url, expiresAt]
+      properties:
+        key: { type: string }
+        url: { type: string, format: uri }
+        expiresAt: { type: string, format: date-time }
+    DownloadURLEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/DownloadURLResponse' }
+    USDString:
+      type: string
+      pattern: '^-?[0-9]+(?:\.[0-9]+)?$'
+      description: Decimal USD amount encoded as a string to avoid binary floating-point loss.