提交任务

POST /v1/tasks

项目	值
Content-Type	application/json
成功状态码	202 Accepted
认证	Authorization: Bearer YOUR_TASK_API_KEY
幂等性	可选 Idempotency-Key 请求头

请求体字段

字段	类型	必填	说明
model	string	是	模型名称。如果 params.model 存在，两者必须一致。
modality	string	否	image、video 或 3d。建议显式传入；省略时仅对能够明确推断模态的模型有效。
params	object	是	模态对应的公共任务参数；可用字段见下文和模型列表。
metadata	object	否	调用方自定义键值对，例如订单 ID 或追踪 ID。

同一个任务 API Key 使用相同 Idempotency-Key 再次提交时，LLMAPI 会直接返回已存在的任务，即使新请求体不同也不会创建新任务。每个逻辑任务必须使用唯一的 Key；视频与 3D 任务成本较高，建议始终提供该请求头。

只有 GET /v1/tasks/models 返回的公共模型及其目录别名才可提交。所有模态都需要配置匹配的 Adapter、已启用渠道模型和档位路由。目前没有注册 3D Adapter，因此 3D 任务当前不可执行。

生成图片

curl https://api.llmapi.site/v1/tasks \
  -H 'Authorization: Bearer YOUR_TASK_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260622-001' \
  -d '{
    "model": "gpt-image-2",
    "modality": "image",
    "params": {
      "model": "gpt-image-2",
      "prompt": "a clean studio product photo of a matte black water bottle",
      "n": 2,
      "image_size": "2K",
      "aspect_ratio": "1:1"
    },
    "metadata": { "order_id": "order-20260622-001" }
  }'

带参考图编辑

参考图放在 params.images[].image_url，支持 Data URL。

{
  "model": "gpt-image-2",
  "modality": "image",
  "params": {
    "model": "gpt-image-2",
    "prompt": "将背景替换为高端摄影棚场景。",
    "images": [{ "image_url": "data:image/png;base64,BASE64_IMAGE" }],
    "n": 1,
    "image_size": "2K",
    "aspect_ratio": "1:1",
    "extra_body": {
      "input_fidelity": "high"
    }
  }
}

规格参数

推荐使用 image_size 和 aspect_ratio 描述图片规格。LLMAPI 会根据实际路由转换成上游需要的格式，调用方通常不需要理解不同模型的协议差异。

字段	示例	说明
image_size	0.5K、1K、2K、3K、4K	用于规格、路由和计费档位。具体可用档位以模型列表返回为准。
aspect_ratio	1:1、16:9、9:16、4:3、3:4、3:2、2:3、4:5、5:4、21:9	用于选择画面比例。具体可用比例以模型列表返回为准。

常见模型与协议的尺寸映射见模型规格。

图片任务中不支持的 params 字段会返回 400，例如 size、resolution、generationConfig、contents。如果需要直接提交 OpenAI Images 风格的 size 参数，请使用 OpenAI Images 兼容接口。

高级扩展参数

少数场景需要精确控制上游参数时，可使用 params.extra_body。LLMAPI 会先根据通用字段生成对应上游请求，再将 extra_body 浅合并到上游请求；同名字段以 extra_body 为准。

推荐优先使用 n、image_size、aspect_ratio、参考图等平台通用字段。若 extra_body 覆盖了上游实际使用的数量或规格，LLMAPI 会按最终上游请求解析出的图片档位计费；单价仍来自该模型在任务调度中的价格配置。

{
  "model": "gemini-3.1-flash-image",
  "modality": "image",
  "params": {
    "model": "gemini-3.1-flash-image",
    "prompt": "使用这个物体生成一张产品图。",
    "images": [{ "image_url": "data:image/png;base64,BASE64_IMAGE" }],
    "n": 1,
    "image_size": "2K",
    "aspect_ratio": "16:9",
    "extra_body": {
      "generationConfig": {
          "temperature": 0.7
      }
    }
  }
}

视频公共协议

视频任务使用 prompt、duration、resolution、aspect_ratio、generate_audio、inputs 和 provider_options。prompt、duration、resolution 和 aspect_ratio 必填。公共解析器要求时长为正整数、其他规格为非空字符串，但模型列表目前不会枚举视频规格值域。优先使用公共字段，协议专属参数放在 provider_options；视频不接受图片协议的 extra_body。

{
  "model": "seedance-video-model",
  "modality": "video",
  "params": {
    "prompt": "从清晨自然过渡到夜晚，镜头缓慢推进",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "inputs": [
      {
        "id": "start",
        "type": "image",
        "role": "first_frame",
        "url": "https://example.com/start.png"
      },
      {
        "id": "end",
        "type": "image",
        "role": "last_frame",
        "url": "https://example.com/end.png"
      }
    ]
  }
}

视频允许的输入组合：图片可用作 first_frame、last_frame 或 reference；视频和音频可用作 reference。一个请求最多包含 16 个输入。Adapter 无法完整构造所请求素材和参数组合的路线会被跳过，不会静默删除字段。

只有公共协议无法表达的控制项才放入 params.provider_options，且不能用它覆盖 model、prompt、duration、resolution、aspect_ratio、inputs 等公共字段。任务参数中不要传凭据。协议专属参数可能缩小可用路线；当前视频渠道要求素材使用上游可访问的公网 HTTP(S) URL。

3D 公共协议

3D V1 公共解析器接受 prompt、inputs、output_format 和 extra_body。prompt 与 inputs 至少提供一个；输入只接受 type=image, role=reference。这只是保留的公共契约；当前没有注册 3D Adapter，因此示例还不能提交到可执行的 3D 模型。

{
  "model": "3d-generation-model",
  "modality": "3d",
  "params": {
    "prompt": "根据参考图生成可用于网页预览的 3D 模型",
    "inputs": [
      {
        "id": "product",
        "type": "image",
        "role": "reference",
        "url": "https://example.com/product.png"
      }
    ],
    "output_format": "glb",
    "extra_body": {
      "texture_quality": "high"
    }
  }
}

提供 output_format 时必须是非空字符串。当前没有公开输出格式白名单，也没有 3D Adapter。面数、贴图质量、骨骼或动画等上游专属参数暂时放在 extra_body，以后由实际 Adapter 校验。

inputs[] 字段

字段	类型	必填	说明
id	string	否	任务内唯一素材名，仅使用字母、数字、_、-。
type	string	是	image、video 或 audio，取决于模态与模型能力。
role	string	是	reference、first_frame 或 last_frame，取决于模态与模型能力。
url	string	是	上游可访问的公网 HTTP(S) URL。

视频与 3D 公共输入不接受 Data URL、本地文件路径或仅平台内部可见的素材地址。解析器最多接受 16 个输入；当前不会发布或执行模型级文件大小、文件格式或媒体时长限制。

响应 — 202 Accepted

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "status": "queued",
  "modality": "image",
  "model": "gpt-image-2",
  "created_at": "2026-06-22T03:10:00Z",
  "estimated_cost": 0.1
}

字段	说明
id	任务 ID，用于轮询和下载资产。
status	新任务初始为 queued；幂等重放返回已有任务的当前状态。
estimated_cost	预估费用（美元），提交时预扣，任务结束时结算或释放。

使用返回的 id 调用 GET /v1/tasks/{id} 查询状态。如需接收状态更新，连接 GET /v1/tasks/events。

错误码

状态码	原因
400	请求体无效或包含不支持的参数，error.message 会指明出错字段。
400 TASK_NO_CAPABLE_ROUTE	当前可用路线不支持本次模态、参数或输入素材组合。
401	API Key 缺失或无效。
403	API Key 未启用任务 API、余额不足，或任务 API 不支持订阅计费。
413	请求体超过服务端配置上限。
429	排队数量或频率达到限制，请使用指数退避重试。
503	任务 API 暂停、价格不可用、存储不可用，或服务暂时不可用。