> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apistable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 发起第一条请求

> 从一套 API 密钥，到可追踪、可核对的生成流程。

> 当前为 API 预览。生成接口尚未接入供应商，成功认证后仍可能返回 503；不会创建任务或扣积分。

## 先了解当前预览

APIstable 分两步建设：先完成网站、账户与执行架构，再接入真实模型供应商。当前模型目录与价格用于展示接口约定，不代表付费推理已经可用。

本页示例说明 API 预览契约。渠道未启用时，应返回供应商尚未配置的错误。复制代码不会执行请求或扣积分。

[查看模型目录](https://apistable.com/models)

## 当前版本的实际行为

| 端点 | 当前行为 |
| - | - |
| GET /v1/models | 公开预览目录，无需密钥。 |
| POST /v1/quotes | 公开参数校验与示例报价，无需密钥，不冻结积分。 |
| GET /v1/balance | 需要 usage:read 权限的有效密钥和可用数据库。 |
| GET /v1/tasks 与 /v1/tasks/{id} | 使用 usage:read 读取账户存储任务，未知 ID 返回 404。 |
| POST /v1/tasks 与 /v1/chat/completions | 认证及适用校验后返回 HTTP 503 provider\_not\_configured，不真实生成或扣费。 |

[OpenAPI JSON](https://apistable.com/openapi.json)
[LLM 可读文档](https://apistable.com/llms.txt)

## 1. 创建 API 密钥

登录后进入控制台 → API Keys。创建时立即保存完整密钥，它只显示一次。建议每个应用或环境使用独立密钥。

```bash theme={null}
export APISTABLE_BASE_URL="https://api.example.com"
export APISTABLE_API_KEY="YOUR_API_KEY"
export APISTABLE_IDEMPOTENCY_KEY="YOUR_UNIQUE_OPERATION_KEY"
```

> 将示例域名替换为实际部署地址。密钥只放在服务端环境变量中，不能写入浏览器代码、URL 或公开仓库。

[管理 API 密钥](https://apistable.com/console/keys)

## 2. 估价并提交

选择精确 Model ID 并校验输入。报价展示合格的低价/官方渠道、每个结果的价格与整次最高冻结积分。API 客户端可以不单独请求报价，但服务端仍会计算并校验价格。

图片和视频使用 output\_count 创建 1–4 个结果项。fallback 默认关闭；开启后，每项在明确可回退失败时可独立尝试官方渠道。

[创建任务](https://docs.apistable.com/cn/create-task.md)
[了解积分](https://docs.apistable.com/cn/credits.md)

## 3. 保存任务 ID

媒体请求受理后返回 HTTP 202 和稳定的 task\_id。保存 ID 并查询原任务，不要再次盲目提交。网络超时不能证明供应商未受理。

* 合理间隔轮询并遵守 Retry-After。queued、running、falling\_back、reconciliation\_required 均不是终态。
* 逐项读取结果；即使其他项尚未结束，也可获取已成功项。在 expires\_at 前下载文件。
* 通知失败不改变已完成生成，也不能导致再次扣费。

[查询任务](https://docs.apistable.com/cn/query-task.md)


## OpenAPI

````yaml openapi.json POST /v1/tasks
openapi: 3.1.0
info:
  title: APIstable API preview
  version: 0.1.0-preview
  description: >-
    Current implemented HTTP surface. / 当前已实现的 HTTP 接口。 Models and quote prices
    are illustrative. Real providers and paid generation are not connected. POST
    /v1/tasks and /v1/chat/completions return 503 provider_not_configured after
    authentication and applicable validation; no credits are reserved or
    charged. Live 202 acceptance, provider callbacks, SSE, idempotent task
    creation, and full model capability adapters remain future integration work.
    Website login sessions are separate from application API keys.
servers:
  - url: https://apistable.com
    description: APIstable API
security: []
tags:
  - name: Models
  - name: Quotes
  - name: Tasks
  - name: Credits
  - name: LLM
paths:
  /v1/tasks:
    post:
      tags:
        - Tasks
      summary: Generation submission placeholder / 生成提交预览
      description: >-
        Requires generations:write. Validates the request, then returns 503
        provider_not_configured. No operation, reservation, or provider attempt
        is created. Idempotency-Key is shown for the future live contract but is
        not consumed by this disabled submission path. Do not treat HTTP 503 as
        a successful generation.
      operationId: createTaskPreview
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Reserved for live acceptance. No task is currently created or
            deduplicated by this header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskRequest'
      responses:
        '400':
          description: Invalid or unsupported input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: invalid_api_key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: insufficient_scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: model_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: payload_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: credit_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            provider_not_configured, model_unavailable, or service_unavailable.
            No live work is accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: provider_not_configured
                  message: >-
                    Live model providers are not connected in this build. No
                    credits were reserved or charged.
      security:
        - bearerAuth: []
components:
  schemas:
    TaskRequest:
      type: object
      additionalProperties: false
      required:
        - model
        - input
      properties:
        model:
          type: string
          minLength: 1
          example: prism-image-2
        input:
          $ref: '#/components/schemas/GenerationInput'
        output_count:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          description: >-
            Target result count. Images/videos accept 1–4; music and LLM must
            remain 1. Not a concurrency guarantee. / 目标结果数，非同时并发保证。
        fallback:
          type: boolean
          default: false
          description: >-
            Authorizes a higher-priced compatible official fallback after an
            eligible confirmed failure. Live execution is disabled in this
            build.
        max_credits:
          type: integer
          minimum: 0
          description: >-
            Whole-request reservation cap. Reject the entire request when
            max_reserved_credits exceeds it.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    GenerationInput:
      type: object
      additionalProperties: false
      required:
        - prompt
      description: >-
        Current preview input. Supported fields vary by modality and exact
        catalog model. No live provider mapping is implied.
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 4000
        duration_seconds:
          type: integer
          description: Video-only; must match the model duration list.
        resolution:
          type: string
          description: Must match the model resolution list.
        aspect_ratio:
          type: string
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
            - '4:3'
        seed:
          type: integer
          minimum: 0
        generate_audio:
          type: boolean
          description: Video only, subject to model support.
        instrumental:
          type: boolean
          description: Music only.
        lyrics:
          type: string
          maxLength: 5000
          description: Music only.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIstable API key
      description: >-
        API key beginning as_. Keep on the server. Scope permissions are checked
        separately.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.