> ## 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 预览。生成接口尚未接入供应商，成功认证后仍可能返回 503；不会创建任务或扣积分。

## 请求参数

| 参数 | 类型 | 规则 |
| - | - | - |
| model | 字符串 · 必填 | 精确模型/操作 ID。 |
| input | 对象 · 必填 | 按当前模型规范校验。 |
| output\_count | 整数 · 默认 1 | 仅图片/视频，目标结果项 1–4。 |
| fallback | 布尔值 · 默认 false | 授权符合条件的官方回退。 |
| max\_credits | 非负整数 · 可选 | 可接受的整次最高冻结。 |

## 真实接入后的受理契约

真实执行启用后，受理成功会原子记录父操作、结果项、冻结积分和持久调度记录。HTTP 202 表示已受理，不表示模型已经完成。

output\_count=4 返回一个包含四个稳定结果项的 task\_id。Worker 在账户和供应商限制内调度，不保证四项同时开始。

> 当前建设阶段尚未连接真实供应商。接口不能伪造生成成功或已完成的付费结果。

## 计划中的幂等受理

真实任务受理启用后，提交 Idempotency-Key 并与输入一起保存。当前 POST /v1/tasks 在创建操作前拒绝真实执行，尚不会因该请求头产生存储操作。同键同输入引用原操作；改变数量、fallback 或费用上限应返回冲突。主动重新生成需新幂等键和新付费操作。

[错误与恢复](https://docs.apistable.com/cn/errors.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.