@spicyapi/sdk 0.2.1 → 0.4.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,14 +353,114 @@ 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]
       operationId: getCreditBalance
-      summary: Get the account balance
+      summary: Get net balance, promotional grants, and approved credit
       responses:
         '200':
-          description: Available, held, and total balance in USD decimal strings.
+          description: Net available, held, and total balances plus funding sources in USD decimal strings. Unused credit is separate from wallet funds; model-scoped grants may not pay for every request.
           content:
             application/json:
               schema:
@@ -794,6 +894,47 @@ components:
       description: Error in the Anthropic `{type:"error",error:{type,message}}` shape.
       content: { application/json: { schema: { $ref: '#/components/schemas/AnthropicErrorBody' } } }
   schemas:
+    FundingGrantItem:
+      type: object
+      required: [id, name, amountUsd, availableUsd, heldUsd, spentUsd, status, startsAt, modelSlugs, customerMemo, createdAt]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        amountUsd: { type: string }
+        availableUsd: { type: string }
+        heldUsd: { type: string }
+        spentUsd: { type: string }
+        status: { type: string }
+        startsAt: { type: string, format: date-time }
+        expiresAt: { type: [string, 'null'], format: date-time }
+        modelSlugs: { type: array, items: { type: string }, description: Empty means all models. }
+        customerMemo: { type: string }
+        createdAt: { type: string, format: date-time }
+    CreditFacilityItem:
+      type: object
+      required: [enabled, limitUsd, availableUsd, usedUsd, heldUsd, status, version]
+      properties:
+        enabled: { type: boolean }
+        limitUsd: { type: string, description: Approved ceiling, not wallet funds. }
+        availableUsd: { type: string }
+        usedUsd: { type: string, description: Outstanding settled principal. }
+        heldUsd: { type: string, description: Credit reserved for accepted tasks. }
+        expiresAt: { type: [string, 'null'], format: date-time }
+        status: { type: string }
+        version: { type: integer, format: int64 }
+    FundingOverview:
+      type: object
+      required: [balanceUsd, heldUsd, prepaidAvailableUsd, grantAvailableUsd, cashShortfallUsd, credit, grants, grantsHasMore]
+      properties:
+        balanceUsd: { type: string, description: Net wallet available balance; may be negative for approved credit consumption or external payment recovery. }
+        heldUsd: { type: string }
+        prepaidAvailableUsd: { type: string, description: Unrestricted prepaid or legacy available funds. }
+        grantAvailableUsd: { type: string, description: Active available grants; model applicability is checked at task admission. }
+        cashShortfallUsd: { type: string, description: External payment recovery shortfall that cannot be covered by grants or credit. }
+        credit: { $ref: '#/components/schemas/CreditFacilityItem' }
+        grants: { type: array, items: { $ref: '#/components/schemas/FundingGrantItem' } }
+        grantsHasMore: { type: boolean }
+
     EnvelopeBase:
       type: object
       required: [code, msg, request_id]
@@ -823,7 +964,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 +1013,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 +1092,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 +1103,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,10 +1128,89 @@ 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]
       properties:
+        funding: { $ref: '#/components/schemas/FundingOverview' }
         available: { $ref: '#/components/schemas/USDString' }
         held: { $ref: '#/components/schemas/USDString' }
         total: { $ref: '#/components/schemas/USDString' }