Cuddler Platform Ark API

openapi: 3.2.0
info:
  title: Cuddler Ai Platform Ark API
  version: 1.0.0
  description: 'Operations tagged platform-ark across 2 of this provider''s published API definitions: cuddler-ai-openapi.json, cuddler-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cuddler.ai
tags:
- name: platform-ark
paths:
  /ark/api/v3/contents/generations/tasks:
    post:
      tags:
      - platform-ark
      security:
      - PlatformApiKey: []
      description: 'BytePlus-compatible subset for allowlisted organizations using Cuddler live keys, not native BytePlus credentials. Public base URL: https://api.cuddler.ai/ark/api/v3. Only compatibility-created tasks are visible; other /v1 tasks are excluded. All keys in the organization share task visibility. Limits and prepaid billing still apply; capacity exhaustion queues without switching provider. Errors use {error:{code,message,param,type},request_id}.'
      summary: Create a BytePlus-compatible video task
      parameters:
      - schema:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
          description: Optional but recommended. Same key and body replay one task; different body returns 409. Without this header, every POST creates a new billable task.
        required: false
        description: Optional but recommended. Same key and body replay one task; different body returns 409. Without this header, every POST creates a new billable task.
        name: Idempotency-Key
        in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformArkCreateRequest'
      responses:
        '200':
          description: Idempotent replay; same vid_ task id
          headers:
            Idempotent-Replayed:
              schema:
                type: string
              description: 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkCreateResponse'
        '202':
          description: Accepted; vid_ task id (not a native cgt_ id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkCreateResponse'
        '400':
          description: Invalid or unsupported field, malformed JSON, or body over 256 KiB; error.param identifies the field where available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '401':
          description: Missing, unknown or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '402':
          description: Insufficient available prepaid balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '403':
          description: Test keys are not allowed; organization or model access is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '404':
          description: Compatibility is disabled, organization is not allowlisted, or task is not visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '409':
          description: Idempotency key conflicts with an earlier request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '429':
          description: Rate or capacity limit; respect Retry-After when present
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '500':
          description: Internal error; quote request_id to support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '503':
          description: Required upstream, pricing or service configuration is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
      operationId: postArkApiV3ContentsGenerationsTasks
      x-operation-id-source: derived
    get:
      tags:
      - platform-ark
      security:
      - PlatformApiKey: []
      description: 'BytePlus-compatible subset for allowlisted organizations using Cuddler live keys, not native BytePlus credentials. Public base URL: https://api.cuddler.ai/ark/api/v3. Only compatibility-created tasks are visible; other /v1 tasks are excluded. All keys in the organization share task visibility. Limits and prepaid billing still apply; capacity exhaustion queues without switching provider. Errors use {error:{code,message,param,type},request_id}.'
      summary: List BytePlus-compatible tasks
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 500
          description: Default 1; canonical positive decimal; no leading zeroes.
        required: false
        description: Default 1; canonical positive decimal; no leading zeroes.
        name: page_num
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          description: Default 20; canonical positive decimal; no leading zeroes.
        required: false
        description: Default 20; canonical positive decimal; no leading zeroes.
        name: page_size
        in: query
      - schema:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - expired
          - cancelled
        required: false
        name: filter.status
        in: query
      - schema:
          type: string
        required: false
        name: filter.model
        in: query
      - schema:
          type: array
          items:
            type: string
            pattern: ^vid_[A-Za-z0-9]{12,40}$
          maxItems: 100
          description: Repeat the query parameter once per task ID; not a comma-separated list.
        required: false
        description: Repeat the query parameter once per task ID; not a comma-separated list.
        name: filter.task_ids
        in: query
      - schema:
          type: string
          enum:
          - default
        required: false
        name: filter.service_tier
        in: query
      responses:
        '200':
          description: Organization's compatibility tasks, paginated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkTaskList'
        '400':
          description: Invalid or unsupported field, malformed JSON, or body over 256 KiB; error.param identifies the field where available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '401':
          description: Missing, unknown or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '403':
          description: Test keys are not allowed; organization or model access is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '404':
          description: Compatibility is disabled, organization is not allowlisted, or task is not visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '429':
          description: Rate or capacity limit; respect Retry-After when present
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '500':
          description: Internal error; quote request_id to support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '503':
          description: Required upstream, pricing or service configuration is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
      operationId: getArkApiV3ContentsGenerationsTasks
      x-operation-id-source: derived
    servers:
    - url: https://api.cuddler.ai
  /ark/api/v3/contents/generations/tasks/{id}:
    get:
      tags:
      - platform-ark
      security:
      - PlatformApiKey: []
      description: 'BytePlus-compatible subset for allowlisted organizations using Cuddler live keys, not native BytePlus credentials. Public base URL: https://api.cuddler.ai/ark/api/v3. Only compatibility-created tasks are visible; other /v1 tasks are excluded. All keys in the organization share task visibility. Limits and prepaid billing still apply; capacity exhaustion queues without switching provider. Errors use {error:{code,message,param,type},request_id}.'
      summary: Get a BytePlus-compatible task
      parameters:
      - schema:
          type: string
          pattern: ^vid_[A-Za-z0-9]{12,40}$
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Task status; successful output URLs expire after about one hour and refresh on GET. Usage is tokens, not USD.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkTask'
        '400':
          description: Invalid or unsupported field, malformed JSON, or body over 256 KiB; error.param identifies the field where available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '401':
          description: Missing, unknown or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '403':
          description: Test keys are not allowed; organization or model access is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '404':
          description: Compatibility is disabled, organization is not allowlisted, or task is not visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '429':
          description: Rate or capacity limit; respect Retry-After when present
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '500':
          description: Internal error; quote request_id to support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '503':
          description: Required upstream, pricing or service configuration is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
      operationId: getArkApiV3ContentsGenerationsTasksById
      x-operation-id-source: derived
    delete:
      tags:
      - platform-ark
      security:
      - PlatformApiKey: []
      description: 'BytePlus-compatible subset for allowlisted organizations using Cuddler live keys, not native BytePlus credentials. Public base URL: https://api.cuddler.ai/ark/api/v3. Only compatibility-created tasks are visible; other /v1 tasks are excluded. All keys in the organization share task visibility. Limits and prepaid billing still apply; capacity exhaustion queues without switching provider. Errors use {error:{code,message,param,type},request_id}.'
      summary: Cancel a queued BytePlus-compatible task
      parameters:
      - schema:
          type: string
          pattern: ^vid_[A-Za-z0-9]{12,40}$
        required: true
        name: id
        in: path
      responses:
        '204':
          description: Cancelled (or already cancelled); no body
        '400':
          description: Invalid or unsupported field, malformed JSON, or body over 256 KiB; error.param identifies the field where available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '401':
          description: Missing, unknown or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '403':
          description: Test keys are not allowed; organization or model access is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '404':
          description: Compatibility is disabled, organization is not allowlisted, or task is not visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '409':
          description: Task is running or otherwise no longer cancellable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '429':
          description: Rate or capacity limit; respect Retry-After when present
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '500':
          description: Internal error; quote request_id to support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
        '503':
          description: Required upstream, pricing or service configuration is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformArkError'
      operationId: deleteArkApiV3ContentsGenerationsTasksById
      x-operation-id-source: derived
    servers:
    - url: https://api.cuddler.ai
components:
  schemas:
    PlatformArkCreateResponse:
      type: object
      properties:
        id:
          type: string
          pattern: ^vid_[A-Za-z0-9]{12,40}$
      required:
      - id
      additionalProperties: false
    PlatformArkCreateRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 100
          description: seedance-2.5 / seedance-2.0 / seedance-2.0-mini, or BytePlus's dreamina-seedance-* name for one of them
        content:
          type: array
          items:
            oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - text
                text:
                  type: string
                  minLength: 1
                  maxLength: 4000
              required:
              - type
              - text
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - image_url
                image_url:
                  type: object
                  properties:
                    url:
                      type: string
                      minLength: 1
                      maxLength: 2048
                  required:
                  - url
                  additionalProperties: false
                role:
                  type: string
                  enum:
                  - first_frame
                  - last_frame
                  - reference_image
              required:
              - type
              - image_url
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - video_url
                video_url:
                  type: object
                  properties:
                    url:
                      type: string
                      minLength: 1
                      maxLength: 2048
                  required:
                  - url
                  additionalProperties: false
                role:
                  type: string
                  enum:
                  - reference_video
              required:
              - type
              - video_url
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - audio_url
                audio_url:
                  type: object
                  properties:
                    url:
                      type: string
                      minLength: 1
                      maxLength: 2048
                  required:
                  - url
                  additionalProperties: false
                role:
                  type: string
                  enum:
                  - reference_audio
              required:
              - type
              - audio_url
              additionalProperties: false
          minItems: 1
          maxItems: 31
        duration:
          type: integer
          minimum: 1
          maximum: 30
        ratio:
          type: string
          enum:
          - '16:9'
          - '9:16'
          - '1:1'
          - '4:3'
          - '3:4'
          - '21:9'
          - adaptive
        resolution:
          type: string
          enum:
          - 480p
          - 720p
          - 1080p
        generate_audio:
          type: boolean
        seed:
          type: integer
          minimum: -1
          maximum: 2147483647
        camera_fixed:
          type: boolean
        return_last_frame:
          type: boolean
        watermark:
          type: boolean
          enum:
          - false
        service_tier:
          type: string
          enum:
          - default
        draft:
          type: boolean
          enum:
          - false
        priority:
          type: number
          enum:
          - 0
        safety_identifier:
          type: string
          minLength: 1
          maxLength: 256
      required:
      - model
      - content
      additionalProperties: false
    PlatformArkTaskList:
      type: object
      properties:
        total:
          type: integer
          minimum: 0
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^vid_[A-Za-z0-9]{12,40}$
              model:
                type: string
              status:
                type: string
                enum:
                - queued
                - running
                - succeeded
                - failed
                - expired
                - cancelled
              created_at:
                type: integer
              updated_at:
                type: integer
              duration:
                type: integer
              ratio:
                type: string
              resolution:
                type: string
              generate_audio:
                type: boolean
              content:
                type: object
                properties:
                  video_url:
                    type: string
                    format: uri
                  last_frame_url:
                    type: string
                    format: uri
                required:
                - video_url
                additionalProperties: false
              usage:
                type: object
                properties:
                  completion_tokens:
                    type: integer
                  total_tokens:
                    type: integer
                required:
                - completion_tokens
                - total_tokens
                additionalProperties: false
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                required:
                - code
                - message
                additionalProperties: false
            required:
            - id
            - model
            - status
            - created_at
            - updated_at
            - duration
            - ratio
            - resolution
            - generate_audio
            additionalProperties: false
      required:
      - total
      - items
      additionalProperties: false
    PlatformArkError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            param:
              type:
              - string
              - 'null'
            type:
              type: string
              enum:
              - invalid_request_error
              - server_error
          required:
          - code
          - message
          - param
          - type
          additionalProperties: false
        request_id:
          type: string
      required:
      - error
      - request_id
      additionalProperties: false
    PlatformArkTask:
      type: object
      properties:
        id:
          type: string
          pattern: ^vid_[A-Za-z0-9]{12,40}$
        model:
          type: string
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - expired
          - cancelled
        created_at:
          type: integer
        updated_at:
          type: integer
        duration:
          type: integer
        ratio:
          type: string
        resolution:
          type: string
        generate_audio:
          type: boolean
        content:
          type: object
          properties:
            video_url:
              type: string
              format: uri
            last_frame_url:
              type: string
              format: uri
          required:
          - video_url
          additionalProperties: false
        usage:
          type: object
          properties:
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
          required:
          - completion_tokens
          - total_tokens
          additionalProperties: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
          - code
          - message
          additionalProperties: false
      required:
      - id
      - model
      - status
      - created_at
      - updated_at
      - duration
      - ratio
      - resolution
      - generate_audio
      additionalProperties: false
  securitySchemes:
    PlatformApiKey:
      type: http
      scheme: bearer
      bearerFormat: cud_sk_live_…
      description: An organization API key issued by Cuddler (cud_sk_live_… spends the organization's prepaid USD balance; cud_sk_test_… can only read the catalog, estimate, and read the balance and usage).
x-refined-from:
- cuddler-ai-openapi.json
- cuddler-ai-openapi.yml