{
  "openapi": "3.0.3",
  "info": {
    "title": "HiAPI API",
    "version": "1.0.0",
    "description": "HiAPI provides Responses and Chat Completions for text models and an asynchronous task API for image, video, and audio generation."
  },
  "servers": [
    {
      "url": "https://api.hiapi.ai",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Chat Completions",
      "description": "Generate text with OpenAI-compatible chat requests."
    },
    {
      "name": "Responses",
      "description": "Generate text with OpenAI-compatible Responses requests and semantic streaming events."
    },
    {
      "name": "Tasks",
      "description": "Create and inspect asynchronous generation tasks."
    }
  ],
  "paths": {
    "/v1/responses": {
      "post": {
        "operationId": "createResponse",
        "summary": "Create a model response",
        "description": "Generate a text response with a model that lists Responses support. Exact reasoning, state, and tool capabilities are model-specific.",
        "tags": [
          "Responses"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponsesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Response object or semantic Server-Sent Events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponsesResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Semantic events ending with response.completed, response.incomplete, or response.failed."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "503": {
            "$ref": "#/components/responses/TemporarilyUnavailable"
          }
        },
        "x-model-contracts": {
          "gpt-6-astra": {
            "$ref": "#/components/schemas/Gpt6AstraResponsesRequest"
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion",
        "description": "Generate a text response with a HiAPI text model. Set stream to true for Server-Sent Events.",
        "tags": [
          "Chat Completions"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion or streaming response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events terminated by data: [DONE]."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "503": {
            "$ref": "#/components/responses/TemporarilyUnavailable"
          }
        }
      }
    },
    "/v1/tasks": {
      "post": {
        "operationId": "createTask",
        "summary": "Create an asynchronous generation task",
        "description": "Submit an image, video, or audio generation task. The response returns a taskId immediately. Poll GET /v1/tasks/{id} or provide callback.url to receive the terminal result.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional idempotency key, up to 255 bytes. Replaying the same request with the same key returns the original taskId.",
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "example": "order-42-submit"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaskRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted",
            "headers": {
              "Idempotent-Replay": {
                "description": "Present with value true when the response replays a previous request.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTaskResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "409": {
            "description": "The first request using this idempotency key is still processing.",
            "headers": {
              "Retry-After": {
                "description": "Suggested retry delay in seconds.",
                "schema": {
                  "type": "string",
                  "example": "5"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": 409,
                  "message": "a request with this Idempotency-Key is still in progress, retry later",
                  "data": null,
                  "error_code": "IDEMPOTENCY_KEY_PROCESSING"
                }
              }
            }
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "description": "The same idempotency key was used with a different request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": 422,
                  "message": "Idempotency-Key was already used with a different request body",
                  "data": null,
                  "error_code": "IDEMPOTENCY_KEY_MISMATCH"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/TemporarilyUnavailable"
          }
        }
      },
      "get": {
        "operationId": "listTasks",
        "summary": "List asynchronous generation tasks",
        "description": "Return tasks created by the current account through the unified task API, newest first.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Items per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/TemporarilyUnavailable"
          }
        }
      }
    },
    "/v1/tasks/{id}": {
      "get": {
        "operationId": "getTask",
        "summary": "Get an asynchronous generation task",
        "description": "Return the current status, output, or failure for a task owned by the current account.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The taskId returned by POST /v1/tasks.",
            "schema": {
              "type": "string",
              "pattern": "^tk-hiapi-",
              "example": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/TaskNotFound"
          },
          "503": {
            "$ref": "#/components/responses/TemporarilyUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key"
      }
    },
    "schemas": {
      "ResponsesRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "deepseek-v4-pro"
          },
          "input": {
            "description": "Text or typed input items. Exact accepted shapes are model-specific.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            ]
          },
          "instructions": {
            "type": "string"
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "max_output_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "reasoning": {
            "type": "object",
            "properties": {
              "effort": {
                "type": "string",
                "enum": [
                  "none",
                  "low",
                  "high",
                  "max"
                ]
              }
            }
          },
          "text": {
            "type": "object",
            "additionalProperties": true
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_choice": {
            "description": "Tool-selection mode or a specific tool choice."
          }
        }
      },
      "ResponsesResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "status",
          "model",
          "output",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "resp_example"
          },
          "object": {
            "type": "string",
            "example": "response"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "incomplete",
              "failed"
            ]
          },
          "model": {
            "type": "string",
            "example": "deepseek-v4-pro"
          },
          "output": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "usage": {
            "type": "object",
            "description": "Input, output, cached-input, reasoning, and total token counts when available.",
            "additionalProperties": true
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role",
          "content"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "type": "string"
          },
          "reasoning_content": {
            "type": "string",
            "description": "Reasoning returned by thinking models or preserved in a continued tool-call turn."
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "deepseek-v4-flash"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            },
            "example": [
              {
                "role": "user",
                "content": "Explain sparse attention in three sentences."
              }
            ]
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "thinking": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "enabled",
                  "disabled"
                ],
                "default": "enabled"
              }
            }
          },
          "reasoning_effort": {
            "type": "string",
            "enum": [
              "high",
              "max"
            ]
          },
          "response_format": {
            "type": "object",
            "additionalProperties": true
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "model",
          "choices",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "chatcmpl_example"
          },
          "object": {
            "type": "string",
            "example": "chat.completion"
          },
          "model": {
            "type": "string",
            "example": "deepseek-v4-flash"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "usage": {
            "type": "object",
            "description": "Prompt, completion, cached-input, and total token counts.",
            "additionalProperties": true
          }
        }
      },
      "CreateTaskRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "HiAPI model ID.",
            "example": "gpt-image-2/text-to-image"
          },
          "route": {
            "type": "string",
            "description": "Optional model route, such as beta, pro, or ext.",
            "pattern": "^[a-zA-Z0-9._-]+$",
            "maxLength": 64,
            "example": "ext"
          },
          "input": {
            "type": "object",
            "description": "Model-specific parameters. See the selected model page for its input schema.",
            "additionalProperties": true,
            "example": {
              "prompt": "A premium product photo on a clean studio background",
              "aspect_ratio": "1:1",
              "resolution": "1K"
            }
          },
          "callback": {
            "$ref": "#/components/schemas/Callback"
          },
          "storage": {
            "type": "string",
            "description": "Requested output storage tier.",
            "enum": [
              "temp",
              "persistent"
            ],
            "default": "temp"
          }
        }
      },
      "Callback": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTP or HTTPS endpoint that receives the terminal task payload.",
            "example": "https://example.com/hiapi/callback"
          },
          "when": {
            "type": "string",
            "description": "Currently only final is supported.",
            "enum": [
              "final"
            ],
            "default": "final"
          }
        }
      },
      "CreateTaskResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "example": 200
          },
          "message": {
            "type": "string",
            "example": "success"
          },
          "data": {
            "type": "object",
            "required": [
              "taskId"
            ],
            "properties": {
              "taskId": {
                "type": "string",
                "example": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
              }
            }
          }
        }
      },
      "TaskStatus": {
        "type": "string",
        "enum": [
          "queued",
          "handling",
          "archiving",
          "success",
          "fail"
        ]
      },
      "TaskOutput": {
        "type": "object",
        "required": [
          "artifactId",
          "url",
          "type",
          "expireAt"
        ],
        "properties": {
          "artifactId": {
            "type": "string",
            "description": "Stable decimal artifact ID. It is returned as a string to preserve JavaScript precision.",
            "example": "123456"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HiAPI CDN URL.",
            "example": "https://cdn.hiapi.ai/tasks/example/result.png"
          },
          "type": {
            "type": "string",
            "description": "Output kind. The enum is extensible.",
            "example": "image"
          },
          "expireAt": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp when temporary access expires. Persistent outputs may return 0.",
            "example": 1777886899
          }
        }
      },
      "TaskFailure": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "TASK_FAILED"
          },
          "message": {
            "type": "string",
            "example": "task failed"
          }
        }
      },
      "Task": {
        "type": "object",
        "required": [
          "taskId",
          "model",
          "status",
          "created",
          "completed",
          "storage"
        ],
        "properties": {
          "taskId": {
            "type": "string",
            "example": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
          },
          "model": {
            "type": "string",
            "description": "Resolved model ID. When route is present, this may include the resolved route suffix.",
            "example": "gpt-image-2/text-to-image@ext"
          },
          "route": {
            "type": "string",
            "description": "Present only when the task was created with an explicit route.",
            "example": "ext"
          },
          "status": {
            "$ref": "#/components/schemas/TaskStatus"
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "Creation time in Unix seconds.",
            "example": 1777282033
          },
          "completed": {
            "type": "integer",
            "format": "int64",
            "description": "Terminal time in Unix seconds, or 0 while the task is not terminal.",
            "example": 1777282099
          },
          "storage": {
            "type": "string",
            "description": "Actual output storage tier.",
            "enum": [
              "temp",
              "persistent",
              "static"
            ],
            "example": "temp"
          },
          "storage_downgraded": {
            "type": "string",
            "description": "Present when persistent storage was requested but the task fell back to temp storage.",
            "example": "insufficient_balance"
          },
          "output": {
            "type": "array",
            "description": "Present only when status is success.",
            "items": {
              "$ref": "#/components/schemas/TaskOutput"
            }
          },
          "error": {
            "$ref": "#/components/schemas/TaskFailure"
          }
        }
      },
      "TaskResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "example": 200
          },
          "message": {
            "type": "string",
            "example": "success"
          },
          "data": {
            "$ref": "#/components/schemas/Task"
          }
        }
      },
      "TaskListResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "example": 200
          },
          "message": {
            "type": "string",
            "example": "success"
          },
          "data": {
            "type": "object",
            "required": [
              "page",
              "size",
              "total",
              "tasks"
            ],
            "properties": {
              "page": {
                "type": "integer",
                "example": 1
              },
              "size": {
                "type": "integer",
                "example": 10
              },
              "total": {
                "type": "integer",
                "example": 42
              },
              "tasks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "example": 400
          },
          "message": {
            "type": "string",
            "example": "invalid request"
          },
          "data": {
            "nullable": true,
            "example": null
          },
          "error_code": {
            "type": "string",
            "example": "INVALID_REQUEST"
          }
        }
      },
      "Gpt6AstraResponsesRequest": {
        "type": "object",
        "description": "Model-specific streaming Responses request for gpt-6-astra. Follow the model reference for supported capabilities and live pricing.",
        "required": [
          "model",
          "input",
          "stream",
          "store"
        ],
        "additionalProperties": false,
        "properties": {
          "model": {
            "type": "string",
            "enum": [
              "gpt-6-astra"
            ]
          },
          "input": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Conversation messages and function-call items; replay required context."
          },
          "stream": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "store": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "instructions": {
            "type": "string"
          },
          "reasoning": {
            "type": "object",
            "properties": {
              "effort": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high",
                  "xhigh",
                  "max"
                ],
                "example": "medium",
                "description": "Examples and Playground select medium. API callers should set reasoning.effort explicitly; omission behavior is not specified."
              }
            }
          },
          "text": {
            "type": "object",
            "description": "Use text.format.type=json_object for JSON mode, or json_schema with name, strict=true and schema for strict structured output."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "tool_choice": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ]
          }
        },
        "externalDocs": {
          "url": "https://www.hiapi.ai/docs/models/text/gpt-6-astra/"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InsufficientBalance": {
        "description": "Insufficient account balance",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Content-Type is not application/json",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "TaskNotFound": {
        "description": "Task not found or not owned by the current account",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "TemporarilyUnavailable": {
        "description": "The task service is temporarily unavailable",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}