0G Labs Provider 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 Provider 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: Provider
paths:
  /providers:
    get:
      description: 'Get all TEE-acknowledged providers, optionally narrowed by service type, on-chain model id, and/or canonical id. `model` and `canonical_id` are independent filters and compose (ANDed): `canonical_id` alone lists every endpoint of a canonical, while `model` + `canonical_id` narrows to a specific endpoint within it. An empty value means "not filtered on" (so no filters = list all). Includes providers with unknown health status (is_healthy=null).'
      tags:
      - Provider
      summary: Get provider list
      parameters:
      - description: Filter by service type (chatbot, text-to-image, speech-to-text)
        name: service_type
        in: query
        schema:
          type: string
      - description: Filter by on-chain model ID (e.g. zai-org/GLM-5.1-FP8); exact model_id match. Empty = not filtered.
        name: model
        in: query
        schema:
          type: string
      - description: '[beta] Filter by canonical model ID (e.g. glm-5.1); lists every endpoint serving that canonical. Composes (AND) with model. Empty = not filtered.'
        name: canonical_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Provider list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ProviderListResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getProviders
      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.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.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.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorDetail'
        request_id:
          type: string
    github_com_0glabs_0g-router_pkg_response.ProviderListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ProviderEntry'
        object:
          type: string
          example: list
    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.ProviderEntry:
      type: object
      properties:
        address:
          type: string
          example: '0x1234567890abcdef'
        architecture:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ModelArchitecture'
        canonical_id:
          description: '[beta] Canonical model id this endpoint serves; empty if unmapped'
          type: string
          x-stability: beta
          example: glm-5.1
        context_length:
          type: integer
        default_parameters:
          type: object
          additionalProperties: {}
        expiration_date:
          description: Upstream model availability expiration (RFC3339); empty = no expiration. Only visible before the instant — an expired endpoint drops out of this listing entirely.
          type: string
        is_healthy:
          description: nil=unknown, true=healthy, false=unhealthy
          type: boolean
          example: true
        latency:
          description: nil=no health data
          type: integer
          example: 150
        max_completion_tokens:
          type: integer
        model_id:
          type: string
          example: qwen-2.5-7b-instruct
        name:
          description: Model metadata (populated when listing providers for a specific model)
          type: string
        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_country:
          description: '[beta] Operator-declared serving country/locality'
          type: string
          x-stability: beta
        provider_name:
          description: 'Operator-declared, descriptive endpoint identity/locality (from the

            broker''s /models metadata). Empty when the operator did not declare them.'
          type: string
          x-stability: beta
        service_type:
          type: string
          example: chatbot
        serving_domain:
          description: '[beta] Operator-declared serving domain'
          type: string
          x-stability: beta
        supported_formats:
          type: array
          items:
            type: string
        supported_parameters:
          type: array
          items:
            type: string
        tee_acknowledged:
          type: boolean
          example: true
        tee_attested:
          type: boolean
        tee_type:
          type: string
        tee_verifier:
          type: string
        trust_mode:
          description: '[beta] Routable trust tier of this endpoint: standard | verified | private. Derived from provider_type — the authoritative tier signal (verifiability is a descriptive TEE label and is empty for standard). Use this to match a request''s provider.trust_mode / X-0G-Provider-Trust-Mode floor.'
          type: string
          x-stability: beta
        type:
          type: string
        uptime:
          description: nil=no health data
          type: number
          example: 99.5
        verifiability:
          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