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

# Create response

> Generate an image or video from a text prompt, or transform an existing image. Built on the [Open Responses](https://huggingface.co/blog/open-responses) spec, a provider-agnostic API standard.

- **Text → image** and **image → image**: Use FLUX models (`black-forest-labs/FLUX.2-dev`)
- **Text → video** and **image → video**: Use Wan models (`Wan-AI/Wan2.2-T2V-A14B-Diffusers`, `Wan-AI/Wan2.2-I2V-A14B-Diffusers`)

Pass a plain string as `input` for text-to-image/video. Pass a structured content array for image-to-image/video.



## OpenAPI

````yaml /reference/openapi-inference.json post /v1/responses
openapi: 3.1.0
info:
  title: Modular Cloud Inference API
  version: 0.1.0
  description: >-
    REST API for Modular Cloud inference. All endpoints are served at
    `https://api.modular.com`.


    Run inference against hosted models. Different model types use different
    endpoints. See the [supported models](/models) page to check which endpoint
    each model uses.
servers:
  - url: https://api.modular.com
security:
  - BearerAuth: []
tags:
  - name: Inference
    description: >-
      Run inference against hosted models. Text and chat models use `POST
      /v1/chat/completions`; image and video generation models use `POST
      /v1/responses`. Check the [supported models](/models) page to see which
      endpoint each model uses.
paths:
  /v1/responses:
    post:
      tags:
        - Inference
      summary: Create response
      description: >-
        Generate an image or video from a text prompt, or transform an existing
        image. Built on the [Open
        Responses](https://huggingface.co/blog/open-responses) spec, a
        provider-agnostic API standard.


        - **Text → image** and **image → image**: Use FLUX models
        (`black-forest-labs/FLUX.2-dev`)

        - **Text → video** and **image → video**: Use Wan models
        (`Wan-AI/Wan2.2-T2V-A14B-Diffusers`, `Wan-AI/Wan2.2-I2V-A14B-Diffusers`)


        Pass a plain string as `input` for text-to-image/video. Pass a
        structured content array for image-to-image/video.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
            examples:
              text-to-image:
                summary: Text → image
                value:
                  model: black-forest-labs/FLUX.2-dev
                  input: A serene mountain landscape at sunset
                  seed: 42
                  provider_options:
                    image:
                      width: 1024
                      height: 1024
                      steps: 28
                      guidance_scale: 7.5
              image-to-image:
                summary: Image → image
                value:
                  model: black-forest-labs/FLUX.2-dev
                  input:
                    - role: user
                      content:
                        - type: input_image
                          image_url: https://example.com/input.jpg
                        - type: input_text
                          text: Transform this into a watercolor painting
                  provider_options:
                    image:
                      width: 1024
                      height: 1024
                      steps: 28
              text-to-video:
                summary: Text → video
                value:
                  model: Wan-AI/Wan2.2-T2V-A14B-Diffusers
                  input: >-
                    A campfire crackles in a forest clearing at night, sparks
                    spiraling upward into a star-filled sky
                  provider_options:
                    image:
                      width: 512
                      height: 512
                      steps: 28
              image-to-video:
                summary: Image → video
                value:
                  model: Wan-AI/Wan2.2-I2V-A14B-Diffusers
                  input:
                    - role: user
                      content:
                        - type: input_image
                          image_url: https://example.com/input.jpg
                        - type: input_text
                          text: >-
                            Animate this scene with gentle wind moving through
                            the grass
                  provider_options:
                    image:
                      width: 480
                      height: 480
                      steps: 28
      responses:
        '200':
          description: Response object containing generated content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
      x-codeSamples:
        - lang: Python
          label: Text → image
          source: |-
            import os
            import base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key=os.environ["MODULAR_API_KEY"],
            )

            response = client.responses.create(
                model="black-forest-labs/FLUX.2-dev",
                input="A serene mountain landscape at sunset",
                extra_body={
                    "provider_options": {
                        "image": {"height": 1024, "width": 1024, "steps": 28}
                    }
                },
            )

            image_data = response.output[0].content[0].image_data
            with open("output.png", "wb") as f:
                f.write(base64.b64decode(image_data))
        - lang: Python
          label: Image → image
          source: |-
            import os
            import base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key=os.environ["MODULAR_API_KEY"],
            )

            response = client.responses.create(
                model="black-forest-labs/FLUX.2-dev",
                input=[
                    {
                        "role": "user",
                        "content": [
                            {"type": "input_image", "image_url": "https://example.com/input.jpg"},
                            {"type": "input_text", "text": "Transform this into a watercolor painting"},
                        ],
                    }
                ],
                extra_body={
                    "provider_options": {
                        "image": {"height": 1024, "width": 1024, "steps": 28}
                    }
                },
            )

            image_data = response.output[0].content[0].image_data
            with open("output.png", "wb") as f:
                f.write(base64.b64decode(image_data))
        - lang: Python
          label: Text → video
          source: |-
            import os
            import base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key=os.environ["MODULAR_API_KEY"],
            )

            response = client.responses.create(
                model="Wan-AI/Wan2.2-T2V-A14B-Diffusers",
                input="A campfire crackles in a forest clearing at night, sparks spiraling upward into a star-filled sky",
                extra_body={
                    "provider_options": {
                        "image": {"height": 512, "width": 512, "steps": 28}
                    }
                },
            )

            video_data = response.output[0].content[0].image_data
            with open("output.mp4", "wb") as f:
                f.write(base64.b64decode(video_data))
        - lang: Python
          label: Image → video
          source: |-
            import os
            import base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key=os.environ["MODULAR_API_KEY"],
            )

            response = client.responses.create(
                model="Wan-AI/Wan2.2-I2V-A14B-Diffusers",
                input=[
                    {
                        "role": "user",
                        "content": [
                            {"type": "input_image", "image_url": "https://example.com/input.jpg"},
                            {"type": "input_text", "text": "Animate this scene with gentle wind moving through the grass"},
                        ],
                    }
                ],
                extra_body={
                    "provider_options": {
                        "image": {"height": 480, "width": 480, "steps": 28}
                    }
                },
            )

            video_data = response.output[0].content[0].image_data
            with open("output.mp4", "wb") as f:
                f.write(base64.b64decode(video_data))
        - lang: Shell
          label: Text → image
          source: |-
            curl -X POST https://api.modular.com/v1/responses \
              -H "Authorization: Bearer $MODULAR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "black-forest-labs/FLUX.2-dev",
                "input": "A serene mountain landscape at sunset",
                "provider_options": {
                  "image": {"height": 1024, "width": 1024, "steps": 28}
                }
              }' | jq -r '.output[0].content[0].image_data' | base64 -d > output.png
        - lang: Shell
          label: Image → image
          source: |-
            curl -X POST https://api.modular.com/v1/responses \
              -H "Authorization: Bearer $MODULAR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "black-forest-labs/FLUX.2-dev",
                "input": [
                  {
                    "role": "user",
                    "content": [
                      {"type": "input_image", "image_url": "https://example.com/input.jpg"},
                      {"type": "input_text", "text": "Transform this into a watercolor painting"}
                    ]
                  }
                ],
                "provider_options": {
                  "image": {"height": 1024, "width": 1024, "steps": 28}
                }
              }' | jq -r '.output[0].content[0].image_data' | base64 -d > output.png
        - lang: Shell
          label: Text → video
          source: |-
            curl -X POST https://api.modular.com/v1/responses \
              -H "Authorization: Bearer $MODULAR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
                "input": "A campfire crackles in a forest clearing at night, sparks spiraling upward into a star-filled sky",
                "provider_options": {
                  "image": {"height": 512, "width": 512, "steps": 28}
                }
              }' | jq -r '.output[0].content[0].image_data' | base64 -d > output.mp4
        - lang: Shell
          label: Image → video
          source: |-
            curl -X POST https://api.modular.com/v1/responses \
              -H "Authorization: Bearer $MODULAR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "Wan-AI/Wan2.2-I2V-A14B-Diffusers",
                "input": [
                  {
                    "role": "user",
                    "content": [
                      {"type": "input_image", "image_url": "https://example.com/input.jpg"},
                      {"type": "input_text", "text": "Animate this scene with gentle wind moving through the grass"}
                    ]
                  }
                ],
                "provider_options": {
                  "image": {"height": 480, "width": 480, "steps": 28}
                }
              }' | jq -r '.output[0].content[0].image_data' | base64 -d > output.mp4
components:
  schemas:
    CreateResponseRequest:
      type: object
      properties:
        model:
          type: string
          description: Model identifier. See the [supported models](/models) page.
          example: black-forest-labs/FLUX.2-dev
        input:
          oneOf:
            - type: string
              description: Text prompt for text-to-image or text-to-video generation.
            - type: array
              description: >-
                Structured input for image-conditioned generation
                (image-to-image or image-to-video). Pass an array containing a
                single user message with `input_image` and `input_text` content
                blocks.
              items:
                $ref: '#/components/schemas/ResponseInputMessage'
          description: >-
            Model input. Pass a plain string for text-to-image/video, or a
            structured content array for image-to-image/video.
        seed:
          type: integer
          description: Random seed for reproducible outputs.
        provider_options:
          $ref: '#/components/schemas/ProviderOptions'
      required:
        - model
        - input
    ResponseObject:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        model:
          type: string
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponseOutputItem'
      required:
        - id
        - object
        - model
        - output
    ResponseInputMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - user
          description: Message role. Always `user` for response inputs.
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponseInputContentPart'
          description: >-
            Array of content blocks. Include an `input_image` block followed by
            an `input_text` block for image-conditioned generation.
      required:
        - role
        - content
    ProviderOptions:
      type: object
      properties:
        image:
          $ref: '#/components/schemas/ImageOptions'
    ResponseOutputItem:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponseContent'
    ResponseInputContentPart:
      type: object
      description: A single content block within a structured response input.
      properties:
        type:
          type: string
          enum:
            - input_text
            - input_image
          description: Content block type.
        text:
          type: string
          description: Text prompt. Required when `type` is `input_text`.
        image_url:
          type: string
          description: >-
            URL or base64 data URI of the source image
            (`data:<mime-type>;base64,<data>`). Required when `type` is
            `input_image`.
      required:
        - type
    ImageOptions:
      type: object
      properties:
        height:
          type: integer
          description: Output height in pixels (must be a multiple of 16).
          default: 512
        width:
          type: integer
          description: Output width in pixels (must be a multiple of 16).
          default: 512
        steps:
          type: integer
          description: >-
            Number of denoising steps. More steps improve quality at the cost of
            latency.
          default: 28
        guidance_scale:
          type: number
          description: >-
            Classifier-free guidance scale. Higher values follow the prompt more
            closely.
          default: 7.5
        num_images:
          type: integer
          description: Number of images to generate.
          default: 1
    ResponseContent:
      type: object
      properties:
        type:
          type: string
          description: Content type (e.g. `image_base64`, `text`).
        image_data:
          type: string
          description: Base64-encoded image or video data.
        text:
          type: string
          description: Generated text content.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Modular Cloud API token. Obtain from the [API Tokens
        page](https://console.modular.com/api_tokens).

````