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

# Flux Kontext Pro 文生图

> Flux Kontext Pro 文生图 API 将自然语言描述生成为图像，覆盖插画、构图完整的场景和设计概念。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

使用 FLUX Kontext Pro 将自然语言描述生成为图像，从插画到构图完整的场景和设计概念。

## 模型

* **blackforestlabs/flux-kontext-pro/text-to-image** - 根据文本提示词生成图像。

## 功能

* 根据文本提示词生成图像。

## 输出选项

### 图像尺寸

* `size`：可选。输出宽高比。可选值：`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`9:21`。默认：`1:1`。

### 输出格式

* `output_format`：可选。输出图像文件格式。可选值：`png`、`jpg`。

## 高级参数

`model` 和可选的 `callback_url` 放在请求根级。所有工作流参数（包括输出选项）都放在 `input` 内。

### 提示词

* `prompt`：必填。描述期望的图像。长度：**1-2,000 个字符**。
* 至少包含一个非空白字符。

## 已验证示例

此示例通过 Vidgo API 生成，也是 Playground 中的默认示例。源图和结果图托管在 Vidgo CDN 上。

![堪萨斯平原上的追风者](https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-kontext-pro/text-to-image/v1/01/output.png)

```json theme={null}
{
  "code": 200,
  "data": {
    "task_id": "2M5RH08SQ7GQGKRE",
    "status": "finished",
    "files": [
      {
        "file_type": "image",
        "file_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-kontext-pro/text-to-image/v1/01/output.png"
      }
    ],
    "created_time": "2026-09-26T10:59:34",
    "error_message": null,
    "progress": 100
  }
}
```


## OpenAPI

````yaml zh/api-manual/image-series/blackforestlabs-flux-kontext-pro-text-to-image.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Flux Kontext Pro 文生图
  description: 使用 FLUX Kontext Pro 将自然语言描述生成为图像，从插画到构图完整的场景和设计概念。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Image Series
      summary: Flux Kontext Pro 文生图
      description: 提交 Flux Kontext Pro 文生图任务：model 和可选的 callback_url 放在请求根级，生成参数放在 input 内。
      operationId: submit_blackforestlabs_flux_kontext_pro_text_to_image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              additionalProperties: true
              properties:
                model:
                  type: string
                  example: blackforestlabs/flux-kontext-pro/text-to-image
                  enum:
                    - blackforestlabs/flux-kontext-pro/text-to-image
                input:
                  type: object
                  required:
                    - prompt
                  properties:
                    prompt:
                      type: string
                      maxLength: 2000
                      minLength: 1
                      description: 描述要生成的图像，1–2,000 个字符，且至少包含一个非空白字符。
                    size:
                      type: string
                      enum:
                        - '1:1'
                        - '4:3'
                        - '3:4'
                        - '16:9'
                        - '9:16'
                        - '21:9'
                        - '9:21'
                      default: '1:1'
                      description: 输出宽高比。默认 1:1。
                    output_format:
                      type: string
                      enum:
                        - png
                        - jpg
                      description: 输出图像文件格式：png 或 jpg。
                  additionalProperties: false
                callback_url:
                  type: string
                  nullable: true
                  description: 公开的 HTTP(S) URL，任务变为 finished 或 failed 时会向其发送 POST 通知。
              description: model 和可选的 callback_url 放在请求根级，生成参数放在 input 内。
            examples:
              default:
                summary: 堪萨斯平原上的追风者
                value:
                  model: blackforestlabs/flux-kontext-pro/text-to-image
                  input:
                    prompt: >-
                      A wide documentary photograph on an empty two-lane gravel
                      road in western Kansas in late June, minutes before a
                      tornado forms. A massive rotating supercell fills the
                      upper two thirds of the sky: a striated, layered
                      mesocyclone shaped like a stacked saucer, dark slate-green
                      underneath, with a low rotating wall cloud on the left
                      side and a thin shaft of hail glowing white behind it. On
                      the right half of the frame, a dusty silver pickup truck
                      is parked on the road shoulder with both front doors open
                      and a tripod-mounted weather instrument mast on its roof.
                      Two storm chasers stand in front of the truck: a tall
                      woman in a faded red windbreaker holds a tablet showing a
                      radar map and points toward the wall cloud; a shorter man
                      in a grey hoodie and baseball cap crouches beside her with
                      a camera on a small tripod. Behind them, golden wheat
                      stubble fields stretch to a flat horizon where a thin
                      strip of warm sunlight breaks under the storm base,
                      lighting the grass and the side of the truck in gold while
                      everything above is dark and heavy. A barbed-wire fence
                      and a leaning wooden utility pole run along the left edge.
                      Strong wind bends the grass and lifts dust from the road.
                      24mm lens, eye level, sharp foreground, natural color,
                      realistic cloud structure, film grain. No text, no logos,
                      no watermark.
                    size: '16:9'
                    output_format: png
              pro-text-to-image-02:
                summary: 雪山山口的旅人，浮世绘
                value:
                  model: blackforestlabs/flux-kontext-pro/text-to-image
                  input:
                    prompt: >-
                      A tall vertical Japanese woodblock print illustration with
                      bold saturated printed color, full-bleed so the image
                      fills the entire frame edge to edge with no border, no
                      margin, no title box and no cartouche. At the top, a
                      jagged snow-covered peak stands against a deep Prussian
                      blue sky that fades to pale blue with a bokashi gradient,
                      with falling snow printed as small white dots. In the
                      middle, a zigzag mountain path climbs between snow-laden
                      pine trees with indigo trunks, and a tiny thatched
                      teahouse with a glowing orange paper lantern sits halfway
                      up. At the bottom, exactly three small travelers walk in a
                      line across a wooden plank bridge over a frozen blue
                      stream: first a man in a wide straw hat and straw rain
                      cape leaning on a staff, second a porter with a wooden
                      frame pack, third a man holding the reins of a brown
                      packhorse with a bright vermilion saddle blanket. Flat
                      areas of color, bold black keyblock outlines, visible wood
                      grain in the sky and snow, slight color misregistration.
                      Palette: Prussian blue, indigo, white, soft grey and
                      vermilion accents. Pure image with no characters or
                      writing of any kind.
                    size: '9:21'
                    output_format: jpg
              pro-text-to-image-03:
                summary: 南极科考站剖面图
                value:
                  model: blackforestlabs/flux-kontext-pro/text-to-image
                  input:
                    prompt: >-
                      A detailed isometric cutaway illustration of a modular
                      Antarctic research station raised on hydraulic stilts
                      above an ice shelf, with the front wall removed to reveal
                      six connected rooms. From left to right: a laboratory with
                      a microscope, sample freezer and ice cores in clear tubes
                      on a rack; a small kitchen with a steaming pot and four
                      people eating at a table; a bunk room with two stacked
                      beds and one person reading; a communications room with a
                      radio operator wearing headphones in front of screens; a
                      gym with a treadmill; and a garage with an orange
                      snowmobile and a tracked vehicle. On the roof: a weather
                      mast with a spinning anemometer, solar panels and a
                      satellite dish. Outside, a blizzard blows snow across the
                      scene, a line of emperor penguins walks past the stilts,
                      and a red flag marks a trail to a distant fuel depot.
                      Clean vector-like line work, soft pastel shading, cool
                      blue-white exterior contrasted with warm yellow interior
                      lighting, consistent isometric perspective, every room
                      clearly readable. No text, no labels, no logos, no
                      watermark.
                    size: '4:3'
              callback:
                summary: 接收完成回调
                value:
                  model: blackforestlabs/flux-kontext-pro/text-to-image
                  input:
                    prompt: >-
                      A wide documentary photograph on an empty two-lane gravel
                      road in western Kansas in late June, minutes before a
                      tornado forms. A massive rotating supercell fills the
                      upper two thirds of the sky: a striated, layered
                      mesocyclone shaped like a stacked saucer, dark slate-green
                      underneath, with a low rotating wall cloud on the left
                      side and a thin shaft of hail glowing white behind it. On
                      the right half of the frame, a dusty silver pickup truck
                      is parked on the road shoulder with both front doors open
                      and a tripod-mounted weather instrument mast on its roof.
                      Two storm chasers stand in front of the truck: a tall
                      woman in a faded red windbreaker holds a tablet showing a
                      radar map and points toward the wall cloud; a shorter man
                      in a grey hoodie and baseball cap crouches beside her with
                      a camera on a small tripod. Behind them, golden wheat
                      stubble fields stretch to a flat horizon where a thin
                      strip of warm sunlight breaks under the storm base,
                      lighting the grass and the side of the truck in gold while
                      everything above is dark and heavy. A barbed-wire fence
                      and a leaning wooden utility pole run along the left edge.
                      Strong wind bends the grass and lifts dust from the road.
                      24mm lens, eye level, sharp foreground, natural color,
                      realistic cloud structure, film grain. No text, no logos,
                      no watermark.
                    size: '16:9'
                    output_format: png
                  callback_url: https://your-domain.com/callback
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - created_time
                    properties:
                      task_id:
                        type: string
                      status:
                        type: string
                        enum:
                          - not_started
                          - running
                          - finished
                          - failed
                      created_time:
                        type: string
                        format: date-time
              example:
                code: 200
                data:
                  task_id: 2M5RH08SQ7GQGKRE
                  status: running
                  created_time: '2026-09-26T10:59:34'
        '400':
          description: 请求校验错误或账户余额不足
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '401':
          description: 凭证无效
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '403':
          description: 拒绝访问
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '404':
          description: 模型未知或已停用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '408':
          description: 请求超时
          content:
            text/plain:
              schema:
                type: string
              example: Request timeout
        '422':
          description: JSON 无效或请求体不是对象
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '429':
          description: 超出速率限制或 API Key 积分限额
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '500':
          description: 内部错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '502':
          description: 任务创建错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '503':
          description: 模型服务暂时不可用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 使用 VIDGO_API_KEY。

````

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