@spicyapi/sdk 0.1.0 → 0.2.1

package/contracts/openapi.yaml

@@ -9,6 +9,10 @@ info:
     `{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.
+
+    The `/v1` operations tagged `OpenAI Compatible` are the one documented
+    exception: they return OpenAI / Anthropic response and error objects so
+    the official SDKs work by changing only `base_url`.
 servers:
   - url: https://api.spicyapi.ai
     description: Production
@@ -17,9 +21,46 @@ tags:
   - name: Models
   - name: Account
   - name: Media
+  - name: OpenAI Compatible
+    description: OpenAI / Anthropic protocol shells under `/v1`. They share authentication, limits, validation and billing with `/api/v1` but use the external protocol's own response and error shapes.
 security:
   - bearerAuth: []
 paths:
+  /api/v1/jobs/quote:
+    post:
+      tags: [Tasks]
+      operationId: quoteTask
+      summary: Quote a task before reserving funds
+      description: |
+        Validates the same model input and admission rules as task creation,
+        without creating a task, reserving funds or starting generation.
+        The signed quote is bound to this account, API key and request and is
+        valid for five minutes. Pass quoteId and expectedCost with the same
+        request to createTask or jobs/stream. New acceptance rejects an expired
+        or changed quote with business code 40901. A replay of an already
+        accepted Idempotency-Key still returns the original task.
+        A quote does not reserve capacity or guarantee future availability.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CreateTaskRequest' }
+      responses:
+        '200':
+          description: Customer price and maximum charge; no funds were reserved.
+          headers:
+            Cache-Control:
+              schema: { type: string, const: no-store }
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TaskQuoteEnvelope' }
+        '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' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '503': { $ref: '#/components/responses/Unavailable' }
   /api/v1/jobs/createTask:
     post:
       tags: [Tasks]
@@ -32,7 +73,7 @@ paths:
 
         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
+        model, input, and callback URL 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
@@ -150,6 +191,50 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorEnvelope' }
         '429': { $ref: '#/components/responses/RateLimited' }
         '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/jobs/stream:
+    post:
+      tags: [Tasks]
+      operationId: streamTask
+      summary: Run a text model and stream the answer
+      description: |
+        Text models only. Applies the same validation, quota, pricing and hold as
+        `createTask`, then keeps the connection open and returns the model answer
+        as a Server-Sent Events stream. Each event is a `data:` line carrying one
+        JSON chunk; the stream ends with `data: [DONE]`.
+
+        The hold is settled when the stream completes. If the upstream call fails
+        before the first event, the response is a normal JSON error and the hold is
+        released. If it fails mid-stream the connection is terminated with an
+        `error` event and the hold is still released — a truncated answer is never
+        charged as a completed one.
+
+        Generation models (image, video, audio) are asynchronous and must use
+        `createTask` with `recordInfo` polling; calling this endpoint for them
+        returns `503`.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTaskRequest'
+      responses:
+        '200':
+          description: Server-Sent Events stream of the model answer.
+          content:
+            text/event-stream:
+              schema: { type: string }
+        '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' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '500': { $ref: '#/components/responses/ServerError' }
+        '503': { $ref: '#/components/responses/Unavailable' }
+
   /api/v1/jobs/retry:
     post:
       tags: [Tasks]
@@ -200,6 +285,7 @@ paths:
         - name: provider
           in: query
           schema: { type: string }
+          description: Exact model creator/author identifier. This never identifies an execution channel.
         - name: task
           in: query
           schema: { type: string }
@@ -244,7 +330,7 @@ paths:
       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 as one segment (for example `family%2Fversion%2Ftask`).
       parameters:
         - name: model
           in: path
@@ -291,7 +377,9 @@ paths:
       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,
+        JPEG, PNG, WebP and GIF images (10 MiB), or MP4/WebM video and
+        MP3/WAV audio (100 MiB, at most 600 seconds). Audio/video commit verifies
+        format and measurable duration; it does not inspect adult content. After PUT,
         call the file commit endpoint and use its spicy:// URI in task input.
       requestBody:
         required: true
@@ -320,8 +408,10 @@ paths:
       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.
+        to an immutable private key. Reference this uploaded file with the returned
+        spicy:// URI. Publicly accessible HTTPS media URLs can instead be passed
+        directly in supported model input fields, without uploading. Repeating
+        a successful commit is idempotent.
       parameters:
         - name: fileId
           in: path
@@ -369,6 +459,272 @@ paths:
         '413': { $ref: '#/components/responses/PayloadTooLarge' }
         '429': { $ref: '#/components/responses/RateLimited' }
         '500': { $ref: '#/components/responses/ServerError' }
+  # ── OpenAI / Anthropic compatible surface ──────────────────────────────
+  # These operations use the response shapes of the external protocols they
+  # imitate (OpenAI error objects, Anthropic error objects, SSE event streams)
+  # instead of the `{code,msg,data,request_id}` envelope. Authentication, rate
+  # limits, validation, pricing and holds are shared with `/api/v1`.
+  /v1/models:
+    get:
+      tags: [OpenAI Compatible]
+      operationId: listOpenAIModels
+      summary: List callable models in the OpenAI `model` list shape
+      description: |
+        Returns every model that can be called right now. `id` is the SpicyAPI
+        model identifier accepted by every `/v1` and `/api/v1` operation;
+        `owned_by` is the model publisher (for example a research lab), never
+        an execution supplier. Pricing is not included; use `/api/v1/models`.
+      responses:
+        '200':
+          description: OpenAI-style model list.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpenAIModelList'
+        '401': { $ref: '#/components/responses/OpenAIError' }
+        '403': { $ref: '#/components/responses/OpenAIError' }
+        '429': { $ref: '#/components/responses/OpenAIError' }
+        '500': { $ref: '#/components/responses/OpenAIError' }
+        '503': { $ref: '#/components/responses/OpenAIError' }
+
+  /v1/chat/completions:
+    post:
+      tags: [OpenAI Compatible]
+      operationId: createChatCompletion
+      summary: OpenAI Chat Completions on a SpicyAPI text model
+      description: |
+        Accepts an OpenAI Chat Completions request. `messages`, `tools`,
+        `tool_choice`, `response_format`, `max_tokens` (or
+        `max_completion_tokens`), `temperature` and `top_p` map onto the
+        model's public input fields of the same name; `stream`,
+        `stream_options`, `user`, `metadata` and `store` are handled by this
+        layer. Any other parameter is forwarded to the model's input schema
+        and rejected with `400` when the model does not declare it — a
+        parameter is never dropped silently.
+
+        `stream: true` returns a Server-Sent Events stream of
+        `chat.completion.chunk` objects terminated by `data: [DONE]`.
+        `stream: false` returns one `chat.completion` object. The same hold,
+        settlement and refund rules as `/api/v1/jobs/stream` apply.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatCompletionRequest'
+      responses:
+        '200':
+          description: One `chat.completion` object, or an SSE stream when `stream` is true.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatCompletion'
+            text/event-stream:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/OpenAIError' }
+        '401': { $ref: '#/components/responses/OpenAIError' }
+        '402': { $ref: '#/components/responses/OpenAIError' }
+        '403': { $ref: '#/components/responses/OpenAIError' }
+        '404': { $ref: '#/components/responses/OpenAIError' }
+        '409': { $ref: '#/components/responses/OpenAIError' }
+        '413': { $ref: '#/components/responses/OpenAIError' }
+        '429': { $ref: '#/components/responses/OpenAIError' }
+        '500': { $ref: '#/components/responses/OpenAIError' }
+        '503': { $ref: '#/components/responses/OpenAIError' }
+
+  /v1/responses:
+    post:
+      tags: [OpenAI Compatible]
+      operationId: createResponse
+      summary: OpenAI Responses API subset on a SpicyAPI text model
+      description: |
+        Accepts the stateless subset of the OpenAI Responses API: `model`,
+        `input` (string or item array with `message`, `function_call` and
+        `function_call_output` items), `instructions`, `max_output_tokens`,
+        `temperature`, `top_p`, `tools` (function tools), `tool_choice`,
+        `text.format`, `reasoning.effort` and `stream`. The request is
+        translated to a chat completion internally. `previous_response_id`
+        is rejected with `400`; send the full history in `input` instead.
+
+        Non-streaming calls return a `response` object with `output[]`
+        (`message` and `function_call` items) and `usage`. Streaming calls
+        emit `response.created`, `response.output_text.delta` and
+        `response.completed` events.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ResponsesRequest'
+      responses:
+        '200':
+          description: One `response` object, or an SSE stream when `stream` is true.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ResponseObject'
+            text/event-stream:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/OpenAIError' }
+        '401': { $ref: '#/components/responses/OpenAIError' }
+        '402': { $ref: '#/components/responses/OpenAIError' }
+        '403': { $ref: '#/components/responses/OpenAIError' }
+        '404': { $ref: '#/components/responses/OpenAIError' }
+        '409': { $ref: '#/components/responses/OpenAIError' }
+        '413': { $ref: '#/components/responses/OpenAIError' }
+        '429': { $ref: '#/components/responses/OpenAIError' }
+        '500': { $ref: '#/components/responses/OpenAIError' }
+        '503': { $ref: '#/components/responses/OpenAIError' }
+
+  /v1/messages:
+    post:
+      tags: [OpenAI Compatible]
+      operationId: createMessage
+      summary: Anthropic Messages API on a SpicyAPI text model
+      description: |
+        Accepts an Anthropic Messages request (`model`, `system`, `messages`
+        with text / image / tool_use / tool_result blocks, `max_tokens`,
+        `temperature`, `top_p`, `stop_sequences`, `tools`, `tool_choice`,
+        `stream`) and translates it to a chat completion internally.
+        Non-streaming calls return an Anthropic `message` object. Streaming
+        calls emit `message_start`, `content_block_start`,
+        `content_block_delta`, `content_block_stop`, `message_delta` and
+        `message_stop` events. Errors use the Anthropic
+        `{type:"error",error:{type,message}}` shape.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AnthropicMessageRequest'
+      responses:
+        '200':
+          description: One Anthropic `message` object, or an SSE stream when `stream` is true.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AnthropicMessage'
+            text/event-stream:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/AnthropicError' }
+        '401': { $ref: '#/components/responses/AnthropicError' }
+        '402': { $ref: '#/components/responses/AnthropicError' }
+        '403': { $ref: '#/components/responses/AnthropicError' }
+        '404': { $ref: '#/components/responses/AnthropicError' }
+        '409': { $ref: '#/components/responses/AnthropicError' }
+        '413': { $ref: '#/components/responses/AnthropicError' }
+        '429': { $ref: '#/components/responses/AnthropicError' }
+        '500': { $ref: '#/components/responses/AnthropicError' }
+        '503': { $ref: '#/components/responses/AnthropicError' }
+
+  /v1/videos:
+    post:
+      tags: [OpenAI Compatible]
+      operationId: createVideo
+      summary: Create a video generation task in the OpenAI Videos shape
+      description: |
+        Projection of `createTask` onto the OpenAI Videos API. `model` must be
+        a video endpoint identifier from `/v1/models`. `prompt` maps to the
+        model's `prompt`; `input_reference` (an HTTPS URL or a committed
+        `spicy://` upload) maps to `image_url` / `image_urls`; `seconds` maps to
+        `duration_seconds`; `size` (`WIDTHxHEIGHT`) maps to `resolution` and/or
+        `aspect_ratio`, or to `width` / `height` when the model declares pixel
+        dimensions. A parameter the selected model does not declare is
+        rejected with `400`. The same hold and idempotency rules as
+        `createTask` apply; the returned object never contains prices.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoCreateRequest'
+      responses:
+        '200':
+          description: The accepted task as a `video` object in `queued` state (an idempotent replay reports the current state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Video'
+        '400': { $ref: '#/components/responses/OpenAIError' }
+        '401': { $ref: '#/components/responses/OpenAIError' }
+        '402': { $ref: '#/components/responses/OpenAIError' }
+        '403': { $ref: '#/components/responses/OpenAIError' }
+        '404': { $ref: '#/components/responses/OpenAIError' }
+        '409': { $ref: '#/components/responses/OpenAIError' }
+        '413': { $ref: '#/components/responses/OpenAIError' }
+        '429': { $ref: '#/components/responses/OpenAIError' }
+        '500': { $ref: '#/components/responses/OpenAIError' }
+        '503': { $ref: '#/components/responses/OpenAIError' }
+
+  /v1/videos/{videoId}:
+    get:
+      tags: [OpenAI Compatible]
+      operationId: retrieveVideo
+      summary: Retrieve a video task as an OpenAI `video` object
+      description: |
+        Task states map to `queued` → `queued`, `running` → `in_progress`,
+        `succeeded` → `completed`, and `failed` / `canceled` / `expired` →
+        `failed` with an `error` object. Only the account and API key that
+        created the task can read it; other identifiers return `404`.
+      parameters:
+        - name: videoId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Current video task state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Video'
+        '401': { $ref: '#/components/responses/OpenAIError' }
+        '403': { $ref: '#/components/responses/OpenAIError' }
+        '404': { $ref: '#/components/responses/OpenAIError' }
+        '429': { $ref: '#/components/responses/OpenAIError' }
+        '500': { $ref: '#/components/responses/OpenAIError' }
+        '503': { $ref: '#/components/responses/OpenAIError' }
+
+  /v1/videos/{videoId}/content:
+    get:
+      tags: [OpenAI Compatible]
+      operationId: downloadVideoContent
+      summary: Redirect to the generated video file
+      description: |
+        Responds `302 Found` with a short-lived signed download URL for the
+        task's primary output, the same address `/api/v1/common/download-url`
+        would issue. `409` while the task is still queued or running; `404`
+        when the task failed or has no downloadable output.
+      parameters:
+        - name: videoId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '302':
+          description: Redirect to the signed media URL. The redirect must not be cached.
+          headers:
+            Location:
+              description: Short-lived signed download URL.
+              schema: { type: string, format: uri }
+            Cache-Control:
+              schema: { type: string, const: no-store }
+        '401': { $ref: '#/components/responses/OpenAIError' }
+        '403': { $ref: '#/components/responses/OpenAIError' }
+        '404': { $ref: '#/components/responses/OpenAIError' }
+        '409': { $ref: '#/components/responses/OpenAIError' }
+        '429': { $ref: '#/components/responses/OpenAIError' }
+        '500': { $ref: '#/components/responses/OpenAIError' }
+        '503': { $ref: '#/components/responses/OpenAIError' }
+
 components:
   securitySchemes:
     bearerAuth:
@@ -395,7 +751,10 @@ components:
       schema: { type: integer, minimum: 1 }
   responses:
     BadRequest:
-      description: Invalid JSON, query, callback URL, model input, or media declaration.
+      description: >-
+        Invalid JSON, query, callback URL, model input, or media declaration.
+        Invalid callBackUrl values return code 400 and msg "Invalid callback URL"
+        with request_id. Submitted hosts, IP addresses, and DNS diagnostics are not echoed.
       content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
     Unauthorized:
       description: Missing, malformed, expired, revoked, or otherwise invalid API key.
@@ -428,6 +787,12 @@ components:
     Unavailable:
       description: No usable deployment or effective customer price exists for the selected model (`50301`).
       content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
+    OpenAIError:
+      description: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return.
+      content: { application/json: { schema: { $ref: '#/components/schemas/OpenAIErrorBody' } } }
+    AnthropicError:
+      description: Error in the Anthropic `{type:"error",error:{type,message}}` shape.
+      content: { application/json: { schema: { $ref: '#/components/schemas/AnthropicErrorBody' } } }
   schemas:
     EnvelopeBase:
       type: object
@@ -445,7 +810,7 @@ components:
           properties:
             code:
               type: integer
-              enum: [400, 401, 40201, 40202, 403, 40301, 40302, 40303, 404, 409, 413, 429, 500, 50301]
+              enum: [400, 401, 40201, 40202, 403, 40301, 40302, 40303, 404, 409, 40901, 413, 429, 500, 50301]
             msg: { type: string }
     CreateTaskRequest:
       type: object
@@ -463,11 +828,39 @@ components:
         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.
+          description: >-
+            Optional public HTTP(S) endpoint for terminal task delivery; HTTPS is recommended.
+            Only ports 80 and 443 are allowed, and URL credentials are rejected.
+            The hostname must resolve to public IP addresses and is checked again when connecting.
+            Invalid values return HTTP 400 with code 400, msg "Invalid callback URL", and request_id.
+        quoteId:
+          type: string
+          maxLength: 4096
+          description: Signed quote returned by jobs/quote for this same account, API key and request. Does not replace Idempotency-Key.
+        expectedCost:
+          allOf:
+            - $ref: '#/components/schemas/USDString'
+          description: Confirmed amount to reserve, with up to nine decimal places. A changed price returns business code 40901 before reservation.
+    TaskQuoteResponse:
+      type: object
+      required: [quoteId, model, estimatedCost, maxCharge, currency, quantity, unit, expiresAt]
+      additionalProperties: false
+      properties:
+        quoteId: { type: string }
+        model: { type: string, description: Resolved endpoint model identifier. }
+        estimatedCost: { $ref: '#/components/schemas/USDString' }
+        maxCharge: { $ref: '#/components/schemas/USDString' }
+        currency: { type: string, const: USD }
+        quantity: { type: string, description: Estimated billable quantity. }
+        unit: { type: string }
+        expiresAt: { type: string, format: date-time }
+    TaskQuoteEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            data: { $ref: '#/components/schemas/TaskQuoteResponse' }
     CreateTaskResponse:
       type: object
       required: [taskId, state, estimatedCost]
@@ -480,7 +873,7 @@ components:
         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.
+          description: Funds held when the task is accepted and the maximum customer charge for that task. Unused funds are released and no later amount is collected above the hold.
     TaskActionRequest:
       type: object
       required: [taskId]
@@ -512,6 +905,31 @@ components:
             code: { type: integer, const: 200 }
             msg: { type: string, const: success }
             data: { $ref: '#/components/schemas/CreateTaskResponse' }
+    TaskOutput:
+      type: object
+      additionalProperties: true
+      description: First-party result metadata. Ready assets include directly usable temporary URLs; no download-ticket request is needed. Poll again to refresh an expired URL. Temporary URLs are bearer access grants; never attach your API key when fetching them.
+      properties:
+        text: { type: string }
+        assets:
+          type: array
+          items: { $ref: '#/components/schemas/TaskOutputAsset' }
+    TaskOutputAsset:
+      type: object
+      additionalProperties: true
+      properties:
+        key: { type: string, description: Compatibility identifier for optional download-url requests. }
+        url: { type: string, format: uri, description: First-party signed GET URL, normally valid for 20 minutes and never beyond the 14-day result retention period. Absent while pending or unavailable. }
+        expiresAt: { type: string, format: date-time, description: Expiry of this URL, not the result retention deadline. }
+        mime: { type: string }
+        width: { type: integer }
+        height: { type: integer }
+        durationSeconds: { type: number }
+        bytes: { type: integer, format: int64 }
+        role: { type: string }
+        nsfw: { type: boolean }
+        pending: { type: boolean }
+        unavailable: { type: boolean }
     TaskRecord:
       type: object
       required: [taskId, model, state, cost, settled, createdAt]
@@ -526,12 +944,9 @@ components:
           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 }
+        output: { $ref: '#/components/schemas/TaskOutput' }
+        errorCode: { type: string, description: Stable SpicyAPI failure identifier; never a raw execution-channel code. }
+        errorMessage: { type: string, description: Safe normalized explanation without internal service names, hosts, task IDs, or raw errors. }
         cost: { $ref: '#/components/schemas/USDString' }
         settled:
           type: boolean
@@ -586,17 +1001,26 @@ components:
           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' }
+        regularPrice: { $ref: '#/components/schemas/USDString' }
+        offerLabel: { type: string }
+        offerPercent: { type: string }
+        offerEndsAt: { type: string, format: date-time }
         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 }
+        model:
+          type: string
+          description: Preferred callable identifier in publisher/model/task form. Image editing uses the edit suffix; previously published identifiers remain accepted.
+          example: bytedance/seedream-5.0-lite/edit
         family:
           type: string
           description: Stable product-family identifier; endpoint variants are listed in `tasks` and expressed by `inputSchema`.
         displayName: { type: string }
-        provider: { type: string }
+        provider:
+          type: string
+          description: Model creator/author identifier. It never identifies an execution channel.
         modality: { type: string, enum: [image, video, audio, text] }
         tasks: { type: array, items: { type: string } }
         async: { type: boolean }
@@ -614,7 +1038,10 @@ components:
         maxOutputDurationSeconds:
           type: integer
           minimum: 1
-          description: Maximum `input.duration` accepted by the model schema; omitted when the model has no declared duration maximum.
+          description: >-
+            Maximum output duration the model schema allows, taken from the `maximum` of its
+            `duration_seconds` property; omitted when that property is absent or has no declared
+            maximum. Distinct from `taskTimeoutSeconds`, which is the platform execution deadline.
         enabled: { type: boolean }
         available: { type: boolean }
         quantityField: { type: string }
@@ -622,11 +1049,22 @@ components:
         startingPrice: { $ref: '#/components/schemas/APIModelPrice' }
         inputSchema:
           type: object
-          description: JSON Schema draft 2020-12 used by `createTask.input` validation.
+          description: >-
+            JSON Schema draft 2020-12 used by `createTask.input` validation and Playground rendering.
+            Standard JSON Schema keywords validate. Presentation hints live only in a per-property `x-ui`
+            object whose keys are snake_case and drawn from a closed set: `widget`, `order`, `label`,
+            `placeholder`, `rows`, `step`, `unit`, `accept`, `max_size_mb`, `advanced`, `primary`,
+            `affects_price`, `visible_when`, `enum_labels`. `x-ui.order` is the only source of field
+            order (descending first). `x-ui.widget` is one of `textarea`, `text`, `upload`,
+            `multi-upload`, `select`, `radio`, `slider`, `number`, `switch`, `json`, `object-list`,
+            `chat-messages`, `hidden`. Root-level composition is limited to `anyOf`, where every branch
+            contains only `required`, and `allOf`, where each branch is `if` (`required` or
+            `properties.*.const`) plus `then` (`required`); `oneOf`, `not` and `dependentSchemas` never
+            appear. Unknown hints must be ignored.
           additionalProperties: true
         version:
           type: string
-          description: Provider/model version label used to detect catalog changes.
+          description: Public model-catalog version label used to detect schema or metadata changes.
         availability:
           type: string
           enum: [planned, available, preview, maintenance]
@@ -681,8 +1119,8 @@ components:
       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 }
+        contentType: { type: string, enum: [image/jpeg, image/png, image/webp, image/gif, video/mp4, video/webm, audio/mpeg, audio/wav] }
+        bytes: { type: integer, minimum: 1, maximum: 104857600, description: Images are limited to 10 MiB; supported audio/video to 100 MiB. }
     UploadURLResponse:
       type: object
       required: [fileId, key, uploadUrl, method, headers, expiresAt, maxBytes]
@@ -710,10 +1148,13 @@ components:
         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] }
+        contentType: { type: string, enum: [image/jpeg, image/png, image/webp, image/gif, video/mp4, video/webm, audio/mpeg, audio/wav] }
         sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
         uri: { type: string, pattern: '^spicy://f/fil_' }
         expiresAt: { type: string, format: date-time }
+        durationSeconds: { type: string, description: Measured audio/video duration in seconds. }
+        width: { type: integer, minimum: 0 }
+        height: { type: integer, minimum: 0 }
     FileCommitEnvelope:
       allOf:
         - $ref: '#/components/schemas/EnvelopeBase'
@@ -750,3 +1191,271 @@ components:
       type: string
       pattern: '^-?[0-9]+(?:\.[0-9]+)?$'
       description: Decimal USD amount encoded as a string to avoid binary floating-point loss.
+
+    # ── OpenAI / Anthropic compatible shapes ───────────────────────────────
+    OpenAIErrorBody:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [message, type, code]
+          properties:
+            message: { type: string }
+            type:
+              type: string
+              enum: [invalid_request_error, authentication_error, permission_error, insufficient_quota, rate_limit_error, server_error]
+            param: { type: [string, 'null'] }
+            code:
+              type: string
+              description: Stable machine-readable reason, for example `invalid_request`, `invalid_api_key`, `insufficient_balance`, `model_not_allowed`, `model_unavailable`, `rate_limit_exceeded`.
+    AnthropicErrorBody:
+      type: object
+      required: [type, error]
+      properties:
+        type: { type: string, const: error }
+        error:
+          type: object
+          required: [type, message]
+          properties:
+            type:
+              type: string
+              enum: [invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, api_error, overloaded_error]
+            message: { type: string }
+    OpenAIModelList:
+      type: object
+      required: [object, data]
+      properties:
+        object: { type: string, const: list }
+        data:
+          type: array
+          items:
+            type: object
+            required: [id, object, created, owned_by]
+            properties:
+              id: { type: string, description: SpicyAPI model identifier; may contain slashes. }
+              object: { type: string, const: model }
+              created: { type: integer, description: Unix seconds of the last catalog update. }
+              owned_by: { type: string, description: Model publisher. }
+    ChatCompletionRequest:
+      type: object
+      required: [model, messages]
+      properties:
+        model: { type: string }
+        messages:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [role]
+            properties:
+              role: { type: string }
+              content:
+                oneOf:
+                  - { type: [string, 'null'] }
+                  - { type: array, items: { type: object, additionalProperties: true } }
+              tool_call_id: { type: string }
+              tool_calls: { type: array, items: { type: object, additionalProperties: true } }
+              reasoning_content:
+                type: string
+                description: Optional assistant reasoning text; availability and message roles follow the selected model input schema.
+            additionalProperties: true
+        stream: { type: boolean, default: false }
+        max_tokens: { type: integer }
+        max_completion_tokens: { type: integer, description: Alias of `max_tokens`. }
+        temperature: { type: number }
+        top_p: { type: number }
+        tools: { type: array, items: { type: object, additionalProperties: true } }
+        tool_choice: { oneOf: [{ type: string }, { type: object, additionalProperties: true }] }
+        response_format: { type: object, additionalProperties: true }
+      additionalProperties:
+        description: Forwarded to the model input schema and rejected when undeclared.
+    ChatCompletion:
+      type: object
+      required: [id, object, created, model, choices]
+      properties:
+        id: { type: string }
+        object: { type: string, const: chat.completion }
+        created: { type: integer }
+        model: { type: string }
+        choices:
+          type: array
+          items:
+            type: object
+            required: [index, message, finish_reason]
+            properties:
+              index: { type: integer }
+              message:
+                type: object
+                properties:
+                  role: { type: string }
+                  content: { type: [string, 'null'] }
+                  refusal: { type: string }
+                  reasoning_content:
+                    type: string
+                    description: Optional reasoning text returned by models that expose it. Streaming chunks use the same field in delta.
+                  tool_calls: { type: array, items: { type: object, additionalProperties: true } }
+              finish_reason: { type: string }
+              logprobs: { type: 'null' }
+        usage:
+          type: object
+          properties:
+            prompt_tokens: { type: integer }
+            completion_tokens: { type: integer }
+            total_tokens: { type: integer }
+            prompt_tokens_details:
+              type: object
+              properties:
+                cached_tokens: { type: integer }
+                cache_creation_input_tokens: { type: integer }
+                cache_read_input_tokens: { type: integer }
+            completion_tokens_details:
+              type: object
+              properties:
+                reasoning_tokens:
+                  type: integer
+                  description: Included in completion_tokens; do not add it again when calculating usage.
+    ResponsesRequest:
+      type: object
+      required: [model, input]
+      properties:
+        model: { type: string }
+        input:
+          oneOf:
+            - { type: string }
+            - { type: array, items: { type: object } }
+        instructions: { type: string }
+        max_output_tokens: { type: integer }
+        temperature: { type: number }
+        top_p: { type: number }
+        tools: { type: array, items: { type: object } }
+        tool_choice: { oneOf: [{ type: string }, { type: object }] }
+        text: { type: object }
+        reasoning: { type: object, properties: { effort: { type: string } } }
+        stream: { type: boolean, default: false }
+    ResponseObject:
+      type: object
+      required: [id, object, created_at, status, model, output]
+      properties:
+        id: { type: string }
+        object: { type: string, const: response }
+        created_at: { type: integer }
+        status: { type: string, enum: [completed, incomplete, in_progress] }
+        model: { type: string }
+        output:
+          type: array
+          items:
+            type: object
+            required: [id, type, status]
+            properties:
+              id: { type: string }
+              type: { type: string, enum: [message, function_call] }
+              status: { type: string }
+              role: { type: string }
+              content:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    type: { type: string, const: output_text }
+                    text: { type: string }
+                    annotations: { type: array, items: { type: object } }
+              call_id: { type: string }
+              name: { type: string }
+              arguments: { type: string }
+        error: { type: 'null' }
+        incomplete_details:
+          type: [object, 'null']
+          properties:
+            reason: { type: string }
+        usage:
+          type: object
+          properties:
+            input_tokens: { type: integer }
+            output_tokens: { type: integer }
+            total_tokens: { type: integer }
+    AnthropicMessageRequest:
+      type: object
+      required: [model, messages, max_tokens]
+      properties:
+        model: { type: string }
+        system:
+          oneOf:
+            - { type: string }
+            - { type: array, items: { type: object } }
+        messages:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [role, content]
+            properties:
+              role: { type: string, enum: [user, assistant] }
+              content:
+                oneOf:
+                  - { type: string }
+                  - { type: array, items: { type: object } }
+        max_tokens: { type: integer }
+        temperature: { type: number }
+        top_p: { type: number }
+        stop_sequences: { type: array, items: { type: string } }
+        tools: { type: array, items: { type: object } }
+        tool_choice: { type: object }
+        stream: { type: boolean, default: false }
+    AnthropicMessage:
+      type: object
+      required: [id, type, role, model, content, stop_reason, usage]
+      properties:
+        id: { type: string }
+        type: { type: string, const: message }
+        role: { type: string, const: assistant }
+        model: { type: string }
+        content:
+          type: array
+          items:
+            type: object
+            required: [type]
+            properties:
+              type: { type: string, enum: [text, tool_use] }
+              text: { type: string }
+              id: { type: string }
+              name: { type: string }
+              input: { type: object }
+        stop_reason: { type: string, enum: [end_turn, max_tokens, tool_use] }
+        stop_sequence: { type: 'null' }
+        usage:
+          type: object
+          properties:
+            input_tokens: { type: integer }
+            output_tokens: { type: integer }
+    VideoCreateRequest:
+      type: object
+      required: [model, prompt]
+      additionalProperties: false
+      properties:
+        model: { type: string, description: Video endpoint identifier from `/v1/models`. }
+        prompt: { type: string }
+        input_reference: { type: string, description: Reference image URL; mapped to the model's `image_url` / `image_urls`. }
+        seconds:
+          oneOf: [{ type: string }, { type: integer }]
+          description: Clip length in seconds; mapped to `duration_seconds`.
+        size: { type: string, pattern: '^[0-9]+x[0-9]+$', description: 'WIDTHxHEIGHT, mapped to `resolution` / `aspect_ratio` (or `width` / `height`).' }
+    Video:
+      type: object
+      required: [id, object, model, status, progress, created_at]
+      properties:
+        id: { type: string, description: Task identifier; also accepted by `/api/v1/jobs/recordInfo`. }
+        object: { type: string, const: video }
+        model: { type: string }
+        status: { type: string, enum: [queued, in_progress, completed, failed] }
+        progress: { type: integer, minimum: 0, maximum: 100, description: 100 when completed, otherwise 0; no fabricated intermediate values. }
+        created_at: { type: integer }
+        completed_at: { type: integer }
+        seconds: { type: string }
+        size: { type: string }
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code: { type: string }
+            message: { type: string }