Runway Tasks API

openapi: 3.0.3
info:
  title: Runway API
  description: >-
    The Runway (RunwayML) developer API for generative AI media. All generation
    is asynchronous: a POST to a generation endpoint creates a task and returns a
    task id, which the client polls on GET /tasks/{id} until the task reaches
    SUCCEEDED or FAILED. Every request must include an Authorization Bearer API
    secret and a dated X-Runway-Version header (for example 2024-11-06). Usage is
    billed in credits (roughly $0.01 per credit) against a developer organization.
    This description was authored by API Evangelist from Runway's public
    documentation and is not an official Runway artifact; verify shapes against
    docs.dev.runwayml.com.
  version: '2024-11-06'
  contact:
    name: Runway
    url: https://docs.dev.runwayml.com
servers:
  - url: https://api.dev.runwayml.com/v1
    description: Runway developer API
security:
  - bearerAuth: []
tags:
  - name: Image-to-Video
    description: Generate video from an image and prompt (Gen-4 Turbo, Gen-4.5).
  - name: Text-to-Image
    description: Generate images from a prompt (Gen-4 Image, Gen-4 Image Turbo).
  - name: Video-to-Video
    description: Edit / restyle an existing video (Aleph).
  - name: Character Performance
    description: Drive a character with a reference performance (Act-Two).
  - name: Text-to-Speech
    description: Synthesize speech audio from text.
  - name: Upscale
    description: Upscale a video to higher resolution.
  - name: Tasks
    description: Poll and cancel asynchronous generation tasks.
  - name: Organization
    description: Usage tier and credit balance for the API organization.
paths:
  /image_to_video:
    post:
      operationId: imageToVideo
      tags:
        - Image-to-Video
      summary: Create an image-to-video task
      description: >-
        Generate video from a starting (and optional ending) image and a text
        prompt. Returns a task id to poll on GET /tasks/{id}.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageToVideoInput'
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /text_to_image:
    post:
      operationId: textToImage
      tags:
        - Text-to-Image
      summary: Create a text-to-image task
      description: >-
        Generate images from a text prompt and optional reference images using
        Gen-4 Image or Gen-4 Image Turbo. Returns a task id to poll.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToImageInput'
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /video_to_video:
    post:
      operationId: videoToVideo
      tags:
        - Video-to-Video
      summary: Create a video-to-video task
      description: >-
        Transform an existing video with a text prompt and optional reference
        keyframes using the Aleph model. Returns a task id to poll.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoToVideoInput'
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /character_performance:
    post:
      operationId: characterPerformance
      tags:
        - Character Performance
      summary: Create a character-performance task
      description: >-
        Drive a target character (image or video) with a reference performance
        video using the Act-Two model. Returns a task id to poll.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CharacterPerformanceInput'
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /text_to_speech:
    post:
      operationId: textToSpeech
      tags:
        - Text-to-Speech
      summary: Create a text-to-speech task
      description: >-
        Synthesize speech audio from text. Billed per character. Returns a task
        id to poll for the resulting audio URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechInput'
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /video_upscale:
    post:
      operationId: videoUpscale
      tags:
        - Upscale
      summary: Create a video-upscale task
      description: >-
        Upscale a generated or uploaded video to a higher resolution. Billed per
        output frame. Returns a task id to poll.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoUpscaleInput'
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /tasks/{id}:
    get:
      operationId: getTask
      tags:
        - Tasks
      summary: Get task detail
      description: >-
        Retrieve the status and output of a generation task. Do not poll more
        often than once every five seconds per task.
      parameters:
        - name: id
          in: path
          required: true
          description: The task id returned by a generation endpoint.
          schema:
            type: string
      responses:
        '200':
          description: The task detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Task not found.
    delete:
      operationId: cancelTask
      tags:
        - Tasks
      summary: Cancel or delete a task
      description: Cancel a running task or delete a completed task's record.
      parameters:
        - name: id
          in: path
          required: true
          description: The task id.
          schema:
            type: string
      responses:
        '204':
          description: The task was cancelled / deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Task not found.
  /organization:
    get:
      operationId: getOrganization
      tags:
        - Organization
      summary: Get organization usage and credit balance
      description: >-
        Return the usage tier and remaining credit balance for the organization
        tied to the API key.
      responses:
        '200':
          description: Organization usage and credit information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API secret created in the Runway developer portal (dev.runwayml.com),
        passed as Authorization Bearer YOUR_API_SECRET. Requests must also send a
        dated X-Runway-Version header.
  responses:
    Unauthorized:
      description: Missing or invalid API secret.
    RateLimited:
      description: Too many requests - the account rate or concurrency limit was exceeded.
  schemas:
    ImageToVideoInput:
      type: object
      required:
        - promptImage
        - model
      properties:
        model:
          type: string
          description: Video model id.
          enum:
            - gen4_turbo
            - gen4.5
            - gen3a_turbo
          example: gen4_turbo
        promptImage:
          description: >-
            A single image URL / data URI, or an array of positioned images
            ({ uri, position: first|last }) for start/end frames.
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  uri:
                    type: string
                  position:
                    type: string
                    enum: [first, last]
        promptText:
          type: string
          description: Text prompt guiding the motion / content.
        ratio:
          type: string
          description: Output resolution, for example 1280:768 or 768:1280.
          example: '1280:768'
        duration:
          type: integer
          description: Clip length in seconds.
          example: 5
        seed:
          type: integer
          description: Deterministic seed (0 to 4294967295).
    TextToImageInput:
      type: object
      required:
        - promptText
        - model
      properties:
        model:
          type: string
          enum:
            - gen4_image
            - gen4_image_turbo
          example: gen4_image
        promptText:
          type: string
        ratio:
          type: string
          example: '1920:1080'
        referenceImages:
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
              tag:
                type: string
        seed:
          type: integer
    VideoToVideoInput:
      type: object
      required:
        - videoUri
        - model
      properties:
        model:
          type: string
          enum:
            - gen4_aleph
          example: gen4_aleph
        videoUri:
          type: string
          description: URL or data URI of the source video to transform.
        promptText:
          type: string
        references:
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
        ratio:
          type: string
        seed:
          type: integer
    CharacterPerformanceInput:
      type: object
      required:
        - character
        - reference
        - model
      properties:
        model:
          type: string
          enum:
            - act_two
          example: act_two
        character:
          type: object
          description: The target character to animate.
          properties:
            type:
              type: string
              enum: [image, video]
            uri:
              type: string
        reference:
          type: object
          description: The reference performance video to transfer.
          properties:
            type:
              type: string
              enum: [video]
            uri:
              type: string
        bodyControl:
          type: boolean
        seed:
          type: integer
    TextToSpeechInput:
      type: object
      required:
        - text
        - model
      properties:
        model:
          type: string
          description: Text-to-speech model id.
          example: eleven_multilingual_v2
        text:
          type: string
        voice:
          type: string
          description: Voice id.
    VideoUpscaleInput:
      type: object
      required:
        - videoUri
        - model
      properties:
        model:
          type: string
          enum:
            - upscale_v1
          example: upscale_v1
        videoUri:
          type: string
          description: URL or data URI of the source video to upscale.
    TaskCreated:
      type: object
      properties:
        id:
          type: string
          description: The task id to poll on GET /tasks/{id}.
    Task:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELLED
        createdAt:
          type: string
          format: date-time
        progress:
          type: number
          description: Completion fraction between 0 and 1 while RUNNING.
        output:
          type: array
          description: Output asset URLs when SUCCEEDED.
          items:
            type: string
        failure:
          type: string
          description: Failure reason when FAILED.
        failureCode:
          type: string
    Organization:
      type: object
      properties:
        creditBalance:
          type: integer
          description: Remaining credits for the organization.
        tier:
          type: object
          description: Usage tier metadata, including per-model concurrency limits.