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

# 建立 Runway 圖像

> 使用 POST /runwayml/v1/text_to_image 啟動會根據文字 Prompt 產生圖像的 Runway 任務，並支援 X-Runway-Version。

使用此端點建立 Runway 圖像生成任務。

## 使用說明

* 傳送必要的 `X-Runway-Version` 標頭，例如 `2024-11-06`
* 使用 `model: gen4_image`
* 此路由至少需要一個 `referenceImages` 項目——僅文字請求會回傳 `reference_images_empty`

## 任務流程

<Steps>
  <Step title="提交生成請求">
    傳送 `promptText`、`ratio`、`model`，以及至少一個 `referenceImages` 物件。
  </Step>

  <Step title="儲存回傳的 id">
    保留回傳的 `id`，因為此路由是非同步的。
  </Step>

  <Step title="輪詢任務">
    使用 [取得 Runway 任務](./runway-to-get-task-details)。如果立即輪詢回傳 `task_not_exist`，請等待幾秒後重試。
  </Step>
</Steps>


## OpenAPI

````yaml api/openapi/video/runway/official-format/post-generate-an-image-from-text.openapi.json POST /runwayml/v1/text_to_image
openapi: 3.1.0
info:
  title: Generate an Image from Text API
  version: 1.0.0
  description: >-
    Create a Runway image-generation task through the official-format CometAPI
    route. At least one reference image is required.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /runwayml/v1/text_to_image:
    post:
      summary: Create a Runway image-generation task
      description: >-
        Submit the prompt, ratio, model, and at least one `referenceImages`
        object.
      operationId: generate_an_image_from_text
      parameters:
        - name: X-Runway-Version
          in: header
          required: true
          description: Runway version header, for example `2024-11-06`.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - promptText
                - ratio
                - seed
                - model
                - referenceImages
                - contentModeration
              properties:
                promptText:
                  type: string
                  description: A non-empty string up to 1000 characters.
                  default: A paper boat floating on calm water at sunrise.
                ratio:
                  type: string
                  description: Aspect ratio of the output image, e.g. `1280:720`.
                  default: '1280:720'
                seed:
                  type: integer
                  description: Random seed for reproducible results.
                  default: 1
                model:
                  type: string
                  description: The model variant to use.
                  default: gen4_image
                referenceImages:
                  type: array
                  description: >-
                    An array of up to three images to be used as references. At
                    least one item is required. `referenceImages` is required.
                  items:
                    type: object
                    properties:
                      uri:
                        type: string
                      tag:
                        type: string
                  default:
                    - uri: >-
                        https://cdn.britannica.com/70/234870-050-D4D024BB/Orange-colored-cat-yawns-displaying-teeth.jpg
                      tag: style_ref
                contentModeration:
                  type: object
                  required:
                    - publicFigureThreshold
                  properties:
                    publicFigureThreshold:
                      type: string
                      description: >-
                        Threshold for public-figure detection. Use `auto` for
                        default behavior.
                  default:
                    publicFigureThreshold: auto
              default:
                promptText: A paper boat floating on calm water at sunrise.
                ratio: '1280:720'
                seed: 1
                model: gen4_image
                referenceImages:
                  - uri: >-
                      https://cdn.britannica.com/70/234870-050-D4D024BB/Orange-colored-cat-yawns-displaying-teeth.jpg
                    tag: style_ref
                contentModeration:
                  publicFigureThreshold: auto
            examples:
              Validated request:
                summary: Validated request
                value:
                  promptText: A paper boat floating on calm water at sunrise.
                  ratio: '1280:720'
                  seed: 1
                  model: gen4_image
                  referenceImages:
                    - uri: >-
                        https://cdn.britannica.com/70/234870-050-D4D024BB/Orange-colored-cat-yawns-displaying-teeth.jpg
                      tag: style_ref
                  contentModeration:
                    publicFigureThreshold: auto
      responses:
        '200':
          description: Task accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                example:
                  id: 31f9c5b2-ea5c-421c-8044-75a6bb53211d
      x-codeSamples:
        - lang: Shell
          label: Default
          source: |
            curl https://api.cometapi.com/runwayml/v1/text_to_image \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                  "promptText": "A paper boat floating on calm water at sunrise.",
                  "ratio": "1280:720",
                  "model": "gen4_image",
                  "referenceImages": [
                    {
                      "uri": "https://your-image-host/reference.jpg",
                      "tag": "ref"
                    }
                  ]
                }'
        - lang: Python
          label: Default
          source: >
            import os

            import requests


            response = requests.post(
                "https://api.cometapi.com/runwayml/v1/text_to_image",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={
                        "promptText": "A paper boat floating on calm water at sunrise.",
                        "ratio": "1280:720",
                        "model": "gen4_image",
                        "referenceImages": [
                                {
                                        "uri": "https://your-image-host/reference.jpg",
                                        "tag": "ref"
                                }
                        ]
                },
            )


            task = response.json()

            print(task["id"])  # poll GET /runwayml/v1/tasks/{id} until the
            output array appears
        - lang: JavaScript
          label: Default
          source: >
            const response = await
            fetch("https://api.cometapi.com/runwayml/v1/text_to_image", {
                method: "POST",
                headers: {
                    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                        "promptText": "A paper boat floating on calm water at sunrise.",
                        "ratio": "1280:720",
                        "model": "gen4_image",
                        "referenceImages": [
                            {
                                "uri": "https://your-image-host/reference.jpg",
                                "tag": "ref"
                            }
                        ]
                    }),
            });


            const task = await response.json();

            console.log(task.id); // poll GET /runwayml/v1/tasks/{id} until the
            output array appears
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````