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

# Create response

> Generate an image or video.

Send a text prompt or image to generate a new image or video.
See the [Supported models](/models) page to find which models support these different modalities.

This API is built on the [Open Responses](https://huggingface.co/blog/open-responses) spec, a provider-agnostic API standard.


## OpenAPI

````yaml /reference/openapi-inference.yaml 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.
paths:
  /v1/responses:
    post:
      tags:
        - Inference
      summary: Create response
      description: Generate an image or 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-klein-4B
                  input: A serene mountain landscape at sunset
                  seed: 42
                  provider_options:
                    image:
                      width: 1024
                      height: 1024
                      steps: 4
                      guidance_scale: 7.5
              image-to-image:
                summary: Image → image
                value:
                  model: black-forest-labs/FLUX.2-klein-4B
                  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: 4
              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'
              examples:
                image:
                  summary: Image response
                  value:
                    id: resp_abc123
                    object: response
                    created_at: 1786985535
                    status: completed
                    model: black-forest-labs/FLUX.2-klein-4B
                    output:
                      - id: msg_abc123_0
                        role: assistant
                        content:
                          - type: output_image
                            image_data: /9j/4AAQSkZJRgABAQAA...
                            format: jpeg
                        status: completed
                    usage:
                      input_tokens: 0
                      output_tokens: 0
                      total_tokens: 0
                      image_generation_details:
                        width: 1024
                        height: 1024
                        megapixels: 1.048576
                        steps: 4
                        image_count: 1
      x-codeSamples:
        - lang: Python
          label: Text → image
          source: |-
            import base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key="<your-api-key>",  # Load your key
            )

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

            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 base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key="<your-api-key>",  # Load your key
            )

            response = client.responses.create(
                model="black-forest-labs/FLUX.2-klein-4B",
                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": 4}
                    }
                },
            )

            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 base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key="<your-api-key>",  # Load your 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 base64
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.modular.com/v1",
                api_key="<your-api-key>",  # Load your 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 <your-api-key>" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "black-forest-labs/FLUX.2-klein-4B",
                "input": "A serene mountain landscape at sunset",
                "provider_options": {
                  "image": {"height": 1024, "width": 1024, "steps": 4}
                }
              }' | 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 <your-api-key>" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "black-forest-labs/FLUX.2-klein-4B",
                "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": 4}
                }
              }' | 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 <your-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 <your-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-klein-4B
        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
          description: Unique identifier for the response.
        object:
          type: string
          enum:
            - response
          description: The object type. Always `response`.
        created_at:
          type: integer
          description: Unix timestamp (in seconds) of when the response was created.
        status:
          type: string
          enum:
            - completed
            - failed
          description: The status of the response.
        model:
          type: string
          description: The model used to generate the response.
        output:
          type: array
          description: The messages generated by the model.
          items:
            $ref: '#/components/schemas/ResponseMessage'
        usage:
          $ref: '#/components/schemas/ResponseUsage'
          description: Usage statistics for the response.
      required:
        - id
        - object
        - created_at
        - status
        - model
        - output
        - usage
    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'
    ResponseMessage:
      type: object
      description: A message in the response output.
      properties:
        id:
          type: string
          description: Unique identifier for this message.
        role:
          type: string
          enum:
            - assistant
          description: The message author. Always `assistant`.
        content:
          type: array
          description: The content blocks generated by the model.
          items:
            oneOf:
              - $ref: '#/components/schemas/OutputImageContent'
                title: Image output
              - $ref: '#/components/schemas/OutputVideoContent'
                title: Video output
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
          description: The status of this message.
      required:
        - id
        - role
        - content
        - status
    ResponseUsage:
      type: object
      description: Usage statistics for the response.
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens. Always `0` for image/video generation.
        output_tokens:
          type: integer
          description: Number of output tokens. Always `0` for image/video generation.
        total_tokens:
          type: integer
          description: Total tokens. Always `0` for image/video generation.
        image_generation_details:
          $ref: '#/components/schemas/ImageGenerationDetails'
          description: >-
            Image generation metadata. Present when the response contains
            generated images.
    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
    OutputImageContent:
      type: object
      description: An image generated by the model.
      properties:
        type:
          type: string
          enum:
            - output_image
          description: Content block type. Always `output_image`.
        image_data:
          type: string
          description: Base64-encoded image data (JPEG by default).
        image_url:
          type: string
          description: URL of the generated image. Present when `response_format` is `url`.
        format:
          type: string
          description: Image format (e.g. `jpeg`, `png`, `webp`).
      required:
        - type
    OutputVideoContent:
      type: object
      description: A video generated by the model.
      properties:
        type:
          type: string
          enum:
            - output_video
          description: Content block type. Always `output_video`.
        video_data:
          type: string
          description: >-
            Base64-encoded video data. Present when `response_format` is
            `b64_json`.
        video_url:
          type: string
          description: URL of the generated video. Present when `response_format` is `url`.
        format:
          type: string
          description: Video format (e.g. `mp4`).
        frames_per_second:
          type: integer
          description: Frame rate of the generated video.
        num_frames:
          type: integer
          description: Number of frames in the generated video.
      required:
        - type
    ImageGenerationDetails:
      type: object
      description: Image generation usage metadata.
      properties:
        width:
          type: integer
          description: Width of each generated image in pixels.
        height:
          type: integer
          description: Height of each generated image in pixels.
        megapixels:
          type: number
          description: Megapixels per image (`width * height / 1e6`).
        steps:
          type: integer
          description: Number of denoising steps used.
        image_count:
          type: integer
          description: Number of images generated.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Modular Cloud API key. Obtain from the [API keys
        page](https://console.modular.com/api_tokens).

````