0G Labs Models API

openapi: 3.2.0
info:
  description: 0G Router is an API gateway between users and the decentralized 0G Compute Provider network.
  title: 0G Router Models API
  termsOfService: https://0g.ai/terms
  contact:
    name: 0G Labs
    url: https://0g.ai
    email: contact@0g.ai
  version: '1.0'
servers:
- url: /v1
tags:
- name: Models
paths:
  /models:
    get:
      description: 'Get all available AI models. By default the response is the **canonical view**: one row per `canonical_id`, with curated registry metadata and endpoints aggregated (max context, union of params/formats, cheapest pricing); `id` is the canonical model id. A model stays listed even when all its endpoints are temporarily unhealthy (health is not a visibility filter; routing falls back to unhealthy endpoints so a listed model is always routable). To enumerate the endpoints behind a canonical id, call `GET /v1/providers?canonical_id=`. provider_address uses OR (match any), input_modality and supported_parameter use AND (must match all).

        `?legacy=true` returns the historical view keyed by the raw provider `model_id` (one row per on-chain model id, including ids not mapped to a registered canonical), for clients that have not migrated to canonical ids. This is a **listing-only** compatibility surface — routing remains canonical-only, so a raw id absent from the model registry is still `404 model_not_found` on the inference path. **[beta]**'
      tags:
      - Models
      summary: Get model list
      parameters:
      - description: '[beta] true: historical raw-model_id-keyed view (listing-only; an unregistered id it lists is still 404 on the inference path). Default false: canonical view (id = canonical_id).'
        name: legacy
        in: query
        schema:
          type: boolean
      - description: '[beta] ''usd'': emit the OpenRouter-standard shape with per-token USD decimal strings under the top-level `pricing` field (for external pricing aggregators, e.g. TKX); models without a USD price are omitted. Default: native prices under `pricing`, USD under `pricing_usd`.'
        name: pricing
        in: query
        schema:
          type: string
          enum:
          - usd
      - description: 'Filter by provider address (OR: match any)'
        name: provider_address
        in: query
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: 'Filter by input modality, e.g. text, image (AND: must support all)'
        name: input_modality
        in: query
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: 'Filter by supported parameter, e.g. temperature (AND: must support all)'
        name: supported_parameter
        in: query
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Model list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelListResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getModels
      x-operation-id-source: derived
components:
  schemas:
    github_com_0glabs_0g-router_pkg_response.ModelArchitecture:
      type: object
      properties:
        input_modalities:
          type: array
          items:
            type: string
        instruct_type:
          type: string
        modality:
          type: string
        output_modalities:
          type: array
          items:
            type: string
        tokenizer:
          type: string
    github_com_0glabs_0g-router_pkg_response.ModelListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelEntry'
        object:
          type: string
          example: list
    github_com_0glabs_0g-router_pkg_response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
          example: bad_request
        message:
          type: string
          example: Invalid request
        type:
          type: string
          example: invalid_request
    github_com_0glabs_0g-router_pkg_response.ModelPriceVariant:
      type: object
      properties:
        dimensions:
          type: object
          additionalProperties:
            type: string
        unit:
          type: string
        unit_price:
          type: string
    github_com_0glabs_0g-router_pkg_response.ModelPricing:
      type: object
      properties:
        cache_write:
          description: 'CacheWrite is the per-token price for writing a prompt token to the cache

            (cache creation) at the default/5-minute TTL, i.e. prompt * write_multiplier.

            [beta] Present only when the provider advertises a cache-write premium

            (write_multiplier > 1) and features.cache_write_premium is enabled; omitted

            otherwise.'
          type: string
        cache_write_1h:
          description: 'CacheWrite1h is the per-token price for writing a prompt token to the cache

            at the 1-hour TTL, i.e. prompt * write_1h_multiplier. [beta] Present only

            when the provider advertises a distinct, valid 1-hour cache-write premium and

            features.cache_write_premium is enabled; omitted otherwise (1-hour writes

            then bill at CacheWrite, or the plain prompt rate when no premium applies).'
          type: string
        cached_prompt:
          type: string
        completion:
          type: string
        image:
          type: string
        prompt:
          type: string
        tiered_pricing:
          type: array
          items:
            $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelPricingTier'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelPriceVariant'
        video:
          description: 'Video is the flat per-effective-output-second price for a single-rate

            video-generation model (wei in the native block, USD decimal in the USD

            block). Variants supersedes it when the model prices by request shape

            (resolution/duration) — see ModelPriceVariant. Both mirror the broker''s

            /models pricing.video / pricing.variants so a video model shows a real

            per-second/per-resolution price instead of a misleading per-token one.'
          type: string
    github_com_0glabs_0g-router_pkg_response.ModelPricingTier:
      type: object
      properties:
        cached_prompt:
          type: string
        completion:
          type: string
        max_input_tokens:
          type: integer
        prompt:
          type: string
    github_com_0glabs_0g-router_pkg_response.ModelEntry:
      type: object
      properties:
        architecture:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelArchitecture'
        context_length:
          type: integer
        created:
          description: Unix timestamp
          type: integer
          example: 1737936000
        default_parameters:
          type: object
          additionalProperties: {}
        description:
          type: string
        expiration_date:
          type: string
        id:
          description: The canonical model id by default; the raw provider model_id when listed with ?legacy=true
          type: string
          example: qwen-2.5-7b-instruct
        max_completion_tokens:
          type: integer
        name:
          type: string
        object:
          type: string
          example: model
        owned_by:
          type: string
          example: 0G Foundation
        pricing:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelPricing'
        pricing_usd:
          description: Per-token USD prices; only set when upstream metadata provides them
          allOf:
          - $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelPricing'
        provider_count:
          description: 'ProviderCount is the number of endpoints serving this canonical,

            counted irrespective of health — it is NOT a count of currently-healthy

            capacity. For per-endpoint health, call GET /v1/providers?canonical_id=<id>

            (each ProviderEntry carries is_healthy).'
          type: integer
        supported_formats:
          type: array
          items:
            type: string
        supported_parameters:
          type: array
          items:
            type: string
        tee_attested:
          type: boolean
        tee_type:
          type: string
        tee_verifier:
          type: string
        type:
          type: string
        verifiability:
          type: string
    github_com_0glabs_0g-router_pkg_response.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorDetail'
        request_id:
          type: string
  securitySchemes:
    ApiKeyAuth:
      description: 'API key for inference, file upload, and async image endpoints. Format: "Bearer sk-..."'
      type: apiKey
      name: Authorization
      in: header
    ManagementKeyAuth:
      description: 'Management key for account read and API key management. Capabilities are scope-limited per key (account:read, keys:read, keys:create, keys:manage). Format: "Bearer mk-..."'
      type: apiKey
      name: Authorization
      in: header