@spicyapi/sdk 0.2.1 → 0.3.0

package/README.md

@@ -16,9 +16,31 @@ const models = await client.listModels({ includeSchema: true });
 ```
 
 Set `SPICY_API_KEY` with your process secret manager. Task creation and retry may reserve funds; use
-stable idempotency keys and explicit user confirmation. Call `quoteTask` with the exact request
-first, display its `estimatedCost`, `maxCharge` and `expiresAt`, then call `createTask` with the
-unchanged input, `quoteId` and `expectedCost`.
+stable idempotency keys and explicit user confirmation. When a caller needs an exact price
+confirmation, call `quoteTask` with the request, display its `estimatedCost`, `maxCharge` and
+`expiresAt`, then pass unchanged input, `quoteId` and `expectedCost` to `createTask` or `run`.
+Pre-authorized server workflows can submit directly at current pricing; separate health, balance and
+quote requests are not mandatory API steps.
+
+## Submit and wait
+
+```ts
+const model = process.env.SPICY_MODEL;
+const operationId = process.env.SPICY_IDEMPOTENCY_KEY;
+if (!model || !operationId) throw new Error("Set a model and a persisted operation key");
+const task = await client.run(
+  { model, input: { prompt: "A quiet mountain lake" } },
+  { idempotencyKey: operationId, onAccepted: ({ taskId }) => console.log({ taskId }) },
+);
+if (task.state === "succeeded") {
+  console.log(task.output?.assets?.[0]?.url);
+}
+```
+
+Use a model and input supported by its current schema. `run` submits once and handles adaptive
+polling, including pending media transfer. Its local timeout includes submission and waiting; timing
+out or aborting does not cancel the accepted task. Resume with the saved task ID. Use a webhook for
+background jobs to avoid polling entirely.
 
 Documentation: <https://spicyapi.ai/en/docs>
 
@@ -85,7 +107,12 @@ explicit type extension in the official client. Reasoning tokens are already inc
 
 Pass a publicly accessible HTTPS image, video, or audio URL directly in the field specified by the
 model schema. Uploading is optional: local files use `createUploadUrl` → PUT → `commitUploadedFile`,
-then the returned account-bound `spicy://` URI (valid for one day).
+then the returned account-bound `spicy://` URI (valid for one day). `uploadFile` wraps these steps;
+`uploadBase64` also accepts a Data URI or raw standard Base64 with an explicit `contentType`. Small
+schema-declared image fields can accept Data URIs directly in `input` (1 MiB decoded per image, 2
+MiB total JSON body, with documented pixel limits). The upload helper is separate and supports
+larger files within upload and model limits. See the
+[media guide](https://docs.spicyapi.ai/en/docs/media).
 
 `getTask` and `waitForTask` return ready media in `output.assets`, including `url`, `expiresAt`,
 MIME, and available dimensions, duration, and byte count. Download `asset.url` directly without
@@ -96,3 +123,25 @@ to refresh a URL; `createDownloadUrl` remains available for older integrations.
 V2 webhooks use the same result fields. A retry keeps the business event and `request_id`, but
 refreshes `url` and `expiresAt`. Verify the signature against the exact received body and
 deduplicate using `request_id`, not a full-body hash. V1 payloads remain unchanged.
+
+## Task history
+
+`listTasks` reads one page of metadata for the current API key. It does not fetch each task's
+inputs, results, or media URLs. Keep the UTC dates fixed while paging and pass the returned cursor
+unchanged:
+
+```ts
+const filters = { from: "2026-09-01", to: "2026-09-07", limit: 20 };
+const page = await client.listTasks(filters);
+if (page.hasMore && page.nextCursor) {
+  const nextPage = await client.listTasks({ ...filters, cursor: page.nextCursor });
+  console.log(nextPage.items);
+}
+```
+
+The UTC interval is `[from,to)`, defaults to seven days ending tomorrow UTC, and cannot exceed 92
+days. Page size defaults to 20 and is capped at 100. Optional `state` and `model` filters narrow the
+results. Each item's `cost` remains an exact decimal USD string; it is final only when `settled` is
+true. Hidden tasks are excluded, so use `getUsage` for settled spending reports. Use `getTask` for a
+selected result, not automatically for every item. History is for discovery and recovery; use `run`,
+`waitForTask`, or webhooks for normal completion tracking.

package/contracts/openapi.yaml

@@ -353,6 +353,106 @@ paths:
         '404': { $ref: '#/components/responses/NotFound' }
         '429': { $ref: '#/components/responses/RateLimited' }
         '500': { $ref: '#/components/responses/ServerError' }
+  /api/v1/jobs:
+    get:
+      tags: [Tasks]
+      operationId: listTasks
+      summary: List task history for the authenticated API key
+      description: |
+        Returns only visible tasks created by this API key and its account,
+        newest first by createdAt and taskId. The list contains metadata only;
+        use recordInfo for a selected task's result. No input, output, signed
+        media URL, or execution-channel information is included.
+        Dates form a UTC half-open interval [from,to), up to 92 days.
+        Default to is tomorrow in UTC; omitted from is seven days before to.
+        Keep all filters, including explicit from/to dates, unchanged while
+        paginating with nextCursor. Pages read live state, not a frozen snapshot.
+        Unknown, duplicate, or empty query parameters are rejected. Queries
+        have a five-second server budget and return 503 on timeout.
+      parameters:
+        - name: from
+          in: query
+          schema: { type: string, format: date }
+          description: Inclusive UTC date in YYYY-MM-DD format.
+        - name: to
+          in: query
+          schema: { type: string, format: date }
+          description: Exclusive UTC date in YYYY-MM-DD format.
+        - name: state
+          in: query
+          schema: { type: string, enum: [queued, running, succeeded, failed, canceled, expired] }
+        - name: model
+          in: query
+          schema: { type: string }
+          description: Exact catalog model identifier or a declared alias.
+        - name: limit
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+        - name: cursor
+          in: query
+          schema: { type: string }
+          description: Opaque nextCursor from the previous page; do not construct it yourself.
+      responses:
+        '200':
+          description: Current-key task summaries without prompt or result payloads.
+          headers:
+            Cache-Control:
+              schema: { type: string, const: no-store }
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/APIKeyTaskListEnvelope' }
+        '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' }
+        '503': { $ref: '#/components/responses/Unavailable' }
+  /api/v1/usage:
+    get:
+      tags: [Account]
+      operationId: getUsage
+      summary: Get usage for the authenticated API key
+      description: |
+        Only tasks created by this API key and its account are included,
+        including hidden historical tasks. Other keys and workspaces cannot
+        be selected. Unknown or repeated query parameters are rejected.
+        Dates form a UTC half-open interval [from,to), up to 92 days.
+        The default to is tomorrow in UTC; omitted from is seven days before to.
+        Calls are attributed to task creation time. Spend sums only settled
+        actual charges for those tasks, never pending holds. Late settlement
+        can change a previous day's spend. These are task usage totals, not
+        a statement of cash movements or remaining API-key budget.
+        An additional account-wide token bucket allows a burst of 30 requests
+        and replenishes 30 tokens per minute, shared by all keys on the account.
+        Observe Retry-After on 429. This reporting limit fails closed when its
+        limiter is unavailable. Queries have a five-second server budget;
+        a timeout returns 503 and suggests retrying a shorter date range.
+      parameters:
+        - name: from
+          in: query
+          schema: { type: string, format: date }
+          description: Inclusive UTC date in YYYY-MM-DD format.
+        - name: to
+          in: query
+          schema: { type: string, format: date }
+          description: Exclusive UTC date in YYYY-MM-DD format.
+      responses:
+        '200':
+          description: Current-key usage with exact USD decimal strings and sparse daily/model buckets.
+          headers:
+            Cache-Control:
+              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/APIKeyUsageEnvelope' }
+        '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' }
+        '503': { $ref: '#/components/responses/Unavailable' }
   /api/v1/chat/credit:
     get:
       tags: [Account]
@@ -823,7 +923,16 @@ components:
           description: Exact `model` value from the model catalog.
         input:
           type: object
-          description: Validated against the selected model's `inputSchema`.
+          description: >-
+            Validated against the selected model's inputSchema. Declared image fields accept
+            public HTTPS URLs, committed spicy:// file URIs, or standard Base64 Data URIs
+            (image/jpeg, image/png, image/webp, image/gif). Inline images are limited to
+            1048576 decoded bytes and 8388608 pixels each, 8192 pixels per side, and
+            16 images / 16777216 pixels in total. The complete JSON request must fit within
+            2097152 bytes. Model-specific limits still apply. Bare Base64, SVG and inline
+            audio/video are not accepted; use HTTPS or file uploads instead. Inline images
+            are stored as account-bound uploaded files; returned input contains file URIs,
+            never the original Base64 bytes. Quote validation does not upload or reserve funds.
           additionalProperties: true
         callBackUrl:
           type: string
@@ -863,9 +972,10 @@ components:
             data: { $ref: '#/components/schemas/TaskQuoteResponse' }
     CreateTaskResponse:
       type: object
-      required: [taskId, state, estimatedCost]
+      required: [taskId, state, estimatedCost, deadlineAt]
       properties:
         taskId: { type: string }
+        deadlineAt: { type: string, format: date-time, description: Server execution deadline fixed at acceptance; not a local wait timeout or result URL expiry. Idempotent replays retain the original deadline. }
         state:
           type: string
           enum: [queued, running, succeeded, failed, canceled, expired]
@@ -941,7 +1051,7 @@ components:
           type: string
           enum: [queued, running, succeeded, failed, canceled, expired]
         input:
-          description: Normalized model input. Omitted after retention redaction.
+          description: Normalized model input; inline images become account-bound file URIs. Omitted after retention redaction.
           type: object
           additionalProperties: true
         output: { $ref: '#/components/schemas/TaskOutput' }
@@ -952,6 +1062,7 @@ components:
           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 }
+        deadlineAt: { type: string, format: date-time, description: Server execution deadline. Present in current responses; historical stored webhook events may omit it. Not the result retention or URL expiry time. }
         completedAt: { type: string, format: date-time }
     TaskRecordEnvelope:
       allOf:
@@ -976,6 +1087,84 @@ components:
         error_message: { type: string }
         cost: { $ref: '#/components/schemas/USDString' }
         created_at: { type: string, format: date-time }
+    APIKeyTaskItem:
+      type: object
+      additionalProperties: false
+      required: [taskId, model, state, cost, settled, createdAt, deadlineAt]
+      properties:
+        taskId: { type: string }
+        model: { type: string, description: Public model identifier. }
+        state: { type: string, enum: [queued, running, succeeded, failed, canceled, expired] }
+        cost:
+          allOf:
+            - $ref: '#/components/schemas/USDString'
+          description: Final charged USD if settled; otherwise the current held estimate.
+        settled: { type: boolean }
+        createdAt: { type: string, format: date-time }
+        deadlineAt: { type: string, format: date-time }
+        completedAt: { type: string, format: date-time }
+    APIKeyTaskListResponse:
+      type: object
+      additionalProperties: false
+      required: [items, hasMore]
+      properties:
+        items:
+          type: array
+          items: { $ref: '#/components/schemas/APIKeyTaskItem' }
+        hasMore: { type: boolean }
+        nextCursor: { type: string, description: Present only when hasMore is true. }
+    APIKeyTaskListEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            code: { type: integer, const: 200 }
+            msg: { type: string, const: success }
+            data: { $ref: '#/components/schemas/APIKeyTaskListResponse' }
+    APIKeyUsageResponse:
+      type: object
+      additionalProperties: false
+      required: [from, to, currency, totalCalls, totalSpend, days, models]
+      properties:
+        from: { type: string, format: date }
+        to: { type: string, format: date }
+        currency: { type: string, const: USD }
+        totalCalls: { type: integer, format: int64, minimum: 0 }
+        totalSpend: { $ref: '#/components/schemas/USDString' }
+        days:
+          type: array
+          items: { $ref: '#/components/schemas/UsageDayItem' }
+        models:
+          type: array
+          items: { $ref: '#/components/schemas/UsageModelItem' }
+    UsageDayItem:
+      type: object
+      additionalProperties: false
+      required: [day, calls, succeeded, failed, spend]
+      properties:
+        day: { type: string, format: date }
+        calls: { type: integer, format: int64, minimum: 0 }
+        succeeded: { type: integer, format: int64, minimum: 0 }
+        failed: { type: integer, format: int64, minimum: 0 }
+        spend: { $ref: '#/components/schemas/USDString' }
+    UsageModelItem:
+      type: object
+      additionalProperties: false
+      required: [model, calls, succeeded, failed, spend]
+      properties:
+        model: { type: string, description: Public model identifier. }
+        calls: { type: integer, format: int64, minimum: 0 }
+        succeeded: { type: integer, format: int64, minimum: 0 }
+        failed: { type: integer, format: int64, minimum: 0 }
+        spend: { $ref: '#/components/schemas/USDString' }
+    APIKeyUsageEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/EnvelopeBase'
+        - type: object
+          required: [data]
+          properties:
+            data: { $ref: '#/components/schemas/APIKeyUsageResponse' }
     Balance:
       type: object
       required: [available, held, total]

package/dist/src/generated/openapi.d.ts

@@ -179,6 +179,68 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List task history for the authenticated API key
+         * @description Returns only visible tasks created by this API key and its account,
+         *     newest first by createdAt and taskId. The list contains metadata only;
+         *     use recordInfo for a selected task's result. No input, output, signed
+         *     media URL, or execution-channel information is included.
+         *     Dates form a UTC half-open interval [from,to), up to 92 days.
+         *     Default to is tomorrow in UTC; omitted from is seven days before to.
+         *     Keep all filters, including explicit from/to dates, unchanged while
+         *     paginating with nextCursor. Pages read live state, not a frozen snapshot.
+         *     Unknown, duplicate, or empty query parameters are rejected. Queries
+         *     have a five-second server budget and return 503 on timeout.
+         */
+        get: operations["listTasks"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get usage for the authenticated API key
+         * @description Only tasks created by this API key and its account are included,
+         *     including hidden historical tasks. Other keys and workspaces cannot
+         *     be selected. Unknown or repeated query parameters are rejected.
+         *     Dates form a UTC half-open interval [from,to), up to 92 days.
+         *     The default to is tomorrow in UTC; omitted from is seven days before to.
+         *     Calls are attributed to task creation time. Spend sums only settled
+         *     actual charges for those tasks, never pending holds. Late settlement
+         *     can change a previous day's spend. These are task usage totals, not
+         *     a statement of cash movements or remaining API-key budget.
+         *     An additional account-wide token bucket allows a burst of 30 requests
+         *     and replenishes 30 tokens per minute, shared by all keys on the account.
+         *     Observe Retry-After on 429. This reporting limit fails closed when its
+         *     limiter is unavailable. Queries have a five-second server budget;
+         *     a timeout returns 503 and suggests retrying a shorter date range.
+         */
+        get: operations["getUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/chat/credit": {
         parameters: {
             query?: never;
@@ -473,7 +535,7 @@ export interface components {
         CreateTaskRequest: {
             /** @description Exact `model` value from the model catalog. */
             model: string;
-            /** @description Validated against the selected model's `inputSchema`. */
+            /** @description Validated against the selected model's inputSchema. Declared image fields accept public HTTPS URLs, committed spicy:// file URIs, or standard Base64 Data URIs (image/jpeg, image/png, image/webp, image/gif). Inline images are limited to 1048576 decoded bytes and 8388608 pixels each, 8192 pixels per side, and 16 images / 16777216 pixels in total. The complete JSON request must fit within 2097152 bytes. Model-specific limits still apply. Bare Base64, SVG and inline audio/video are not accepted; use HTTPS or file uploads instead. Inline images are stored as account-bound uploaded files; returned input contains file URIs, never the original Base64 bytes. Quote validation does not upload or reserve funds. */
             input: {
                 [key: string]: unknown;
             };
@@ -506,6 +568,11 @@ export interface components {
         };
         CreateTaskResponse: {
             taskId: string;
+            /**
+             * Format: date-time
+             * @description Server execution deadline fixed at acceptance; not a local wait timeout or result URL expiry. Idempotent replays retain the original deadline.
+             */
+            deadlineAt: string;
             /**
              * @description `queued` for a new submission; an idempotent replay reports the original task's current state.
              * @enum {string}
@@ -574,7 +641,7 @@ export interface components {
             model: string;
             /** @enum {string} */
             state: "queued" | "running" | "succeeded" | "failed" | "canceled" | "expired";
-            /** @description Normalized model input. Omitted after retention redaction. */
+            /** @description Normalized model input; inline images become account-bound file URIs. Omitted after retention redaction. */
             input?: {
                 [key: string]: unknown;
             };
@@ -588,6 +655,11 @@ export interface components {
             settled: boolean;
             /** Format: date-time */
             createdAt: string;
+            /**
+             * Format: date-time
+             * @description Server execution deadline. Present in current responses; historical stored webhook events may omit it. Not the result retention or URL expiry time.
+             */
+            deadlineAt?: string;
             /** Format: date-time */
             completedAt?: string;
         };
@@ -616,6 +688,73 @@ export interface components {
             /** Format: date-time */
             created_at: string;
         };
+        APIKeyTaskItem: {
+            taskId: string;
+            /** @description Public model identifier. */
+            model: string;
+            /** @enum {string} */
+            state: "queued" | "running" | "succeeded" | "failed" | "canceled" | "expired";
+            /** @description Final charged USD if settled; otherwise the current held estimate. */
+            cost: components["schemas"]["USDString"];
+            settled: boolean;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            deadlineAt: string;
+            /** Format: date-time */
+            completedAt?: string;
+        };
+        APIKeyTaskListResponse: {
+            items: components["schemas"]["APIKeyTaskItem"][];
+            hasMore: boolean;
+            /** @description Present only when hasMore is true. */
+            nextCursor?: string;
+        };
+        APIKeyTaskListEnvelope: components["schemas"]["EnvelopeBase"] & {
+            /** @constant */
+            code?: 200;
+            /** @constant */
+            msg?: "success";
+            data: components["schemas"]["APIKeyTaskListResponse"];
+        };
+        APIKeyUsageResponse: {
+            /** Format: date */
+            from: string;
+            /** Format: date */
+            to: string;
+            /** @constant */
+            currency: "USD";
+            /** Format: int64 */
+            totalCalls: number;
+            totalSpend: components["schemas"]["USDString"];
+            days: components["schemas"]["UsageDayItem"][];
+            models: components["schemas"]["UsageModelItem"][];
+        };
+        UsageDayItem: {
+            /** Format: date */
+            day: string;
+            /** Format: int64 */
+            calls: number;
+            /** Format: int64 */
+            succeeded: number;
+            /** Format: int64 */
+            failed: number;
+            spend: components["schemas"]["USDString"];
+        };
+        UsageModelItem: {
+            /** @description Public model identifier. */
+            model: string;
+            /** Format: int64 */
+            calls: number;
+            /** Format: int64 */
+            succeeded: number;
+            /** Format: int64 */
+            failed: number;
+            spend: components["schemas"]["USDString"];
+        };
+        APIKeyUsageEnvelope: components["schemas"]["EnvelopeBase"] & {
+            data: components["schemas"]["APIKeyUsageResponse"];
+        };
         Balance: {
             available: components["schemas"]["USDString"];
             held: components["schemas"]["USDString"];
@@ -1395,6 +1534,78 @@ export interface operations {
             500: components["responses"]["ServerError"];
         };
     };
+    listTasks: {
+        parameters: {
+            query?: {
+                /** @description Inclusive UTC date in YYYY-MM-DD format. */
+                from?: string;
+                /** @description Exclusive UTC date in YYYY-MM-DD format. */
+                to?: string;
+                state?: "queued" | "running" | "succeeded" | "failed" | "canceled" | "expired";
+                /** @description Exact catalog model identifier or a declared alias. */
+                model?: string;
+                limit?: number;
+                /** @description Opaque nextCursor from the previous page; do not construct it yourself. */
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Current-key task summaries without prompt or result payloads. */
+            200: {
+                headers: {
+                    "Cache-Control"?: "no-store";
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIKeyTaskListEnvelope"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            429: components["responses"]["RateLimited"];
+            500: components["responses"]["ServerError"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    getUsage: {
+        parameters: {
+            query?: {
+                /** @description Inclusive UTC date in YYYY-MM-DD format. */
+                from?: string;
+                /** @description Exclusive UTC date in YYYY-MM-DD format. */
+                to?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Current-key usage with exact USD decimal strings and sparse daily/model buckets. */
+            200: {
+                headers: {
+                    "Cache-Control"?: "no-store";
+                    "X-RateLimit-Limit": components["headers"]["RateLimitLimit"];
+                    "X-RateLimit-Remaining": components["headers"]["RateLimitRemaining"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIKeyUsageEnvelope"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            429: components["responses"]["RateLimited"];
+            500: components["responses"]["ServerError"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
     getCreditBalance: {
         parameters: {
             query?: never;