api-stock-com Task Management API

openapi: 3.2.0
info:
  title: Stock Com Task Management API
  version: '1.0'
  contact: {}
  description: 'Operations tagged Task Management across 2 of this provider''s published API definitions: api-stock-com-openapi.json, api-stock-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.api-stock.com
  description: Production
tags:
- name: Task Management
paths:
  /api/v1/task/status/{taskId}:
    get:
      description: Query the execution status of image and video generation tasks and retrieve results when complete
      operationId: TaskController_getTaskStatus
      parameters:
      - name: taskId
        required: true
        in: path
        description: Unique task identifier returned from the submit endpoint
        schema:
          example: task-unified-1757165031-uyujaw3d
          type: string
      responses:
        '200':
          description: Task status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponseDto'
        '401':
          description: Unauthorized - Check your API key
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponseDto'
              examples:
                taskNotFound:
                  value:
                    code: 404
                    error:
                      message: Task not found
                      type: NotFound
                      code: task_not_found
      security:
      - apiKey: []
      summary: Get task status
      tags:
      - Task Management
    servers:
    - url: https://api.api-stock.com
      description: Production
components:
  schemas:
    MediaFileDto:
      type: object
      properties:
        fileUrl:
          type: string
          description: Direct URL to the generated file (retained for 3 days)
          example: https://s3.api-stock.com/generated/image-abc123.jpg
        fileType:
          type: string
          description: 'Type of media file: ''image'', ''video'' or ''music'''
          enum:
          - image
          - video
          - music
          example: image
      required:
      - fileUrl
      - fileType
    TaskDataDto:
      type: object
      properties:
        taskId:
          type: string
          description: Unique task identifier
          example: 019ca881-9503-7270-a560-f00fc2b15785
        status:
          type: string
          description: 'Task status: not_started, processing, finished, failed, expired'
          enum:
          - not_started
          - processing
          - finished
          - failed
          - expired
          example: finished
        files:
          description: Generated media files (populated when status is finished)
          example:
          - file_url: https://s3.api-stock.com/generated/image-abc123.jpg
            file_type: image
          type: array
          items:
            $ref: '#/components/schemas/MediaFileDto'
        output:
          type:
          - object
          - 'null'
          description: Structured result data. For data generations (e.g. Suno lyrics text or created persona) this is the full result. For media generations it carries extra metadata when available — e.g. Suno music returns `tracks` with per-track title, duration, lyrics, tags and cover image URLs (order matches `files`).
        createdTime:
          type: string
          description: ISO 8601 timestamp of task creation
          example: '2025-11-12T10:30:00'
        errorMessage:
          type:
          - string
          - 'null'
          description: Error description (when status is failed)
          example: null
      required:
      - taskId
      - status
      - files
      - createdTime
    NotFoundErrorResponseDto:
      type: object
      properties:
        code:
          type: number
          description: HTTP status code
          example: 404
        error:
          description: Error details
          allOf:
          - $ref: '#/components/schemas/ErrorDetails'
      required:
      - code
      - error
    TaskStatusResponseDto:
      type: object
      properties:
        code:
          type: number
          description: HTTP status code
          example: 200
        data:
          description: Task data
          allOf:
          - $ref: '#/components/schemas/TaskDataDto'
      required:
      - code
      - data
    ErrorDetails:
      type: object
      properties:
        message:
          type: string
          description: Human-readable cause. English, stable — safe to log, not meant for display to end users in other languages.
        type:
          type: string
          description: Error type
        code:
          type: string
          description: Stable machine-readable code. Match on this rather than on `message` — clients use it to render their own localized wording.
          example: insufficient_balance
      required:
      - message
      - type
      - code
  securitySchemes:
    apiKey:
      scheme: bearer
      bearerFormat: API Key
      type: http
      description: Enter your API key
externalDocs:
  description: API Stock documentation
  url: https://docs.api-stock.com
x-refined-from:
- api-stock-com-openapi.json
- api-stock-com-openapi.json