---
openapi: 3.1.0
info:
title: Compose Inference
version: 0.8.6
summary: Model discovery and Responses API contracts.
description: |
Canonical contract for Compose model discovery and Responses-only model execution. Payment and session primitives are owned by the
Compose x402 contract.
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
servers:
- url: https://api.compose.market
x-speakeasy-server-id: inference
description: Production inference endpoint
- url: http://127.0.0.1:3000
x-speakeasy-server-id: local
description: Local inference development endpoint
tags:
- name: health
- name: models
- name: modality
- name: inference
security: []
paths:
"/health":
get:
tags:
- health
operationId: check
responses:
'200':
description: API service health.
content:
application/json:
schema:
"$ref": "#/components/schemas/HealthResponse"
"/v1/models":
get:
tags:
- models
operationId: list
parameters:
- "$ref": "#/components/parameters/ProviderQuery"
- "$ref": "#/components/parameters/ModalityQuery"
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 200
responses:
'200':
description: Curated model list.
content:
application/json:
schema:
"$ref": "#/components/schemas/ModelListResponse"
"/v1/models/all":
get:
tags:
- models
operationId: list_all
responses:
'200':
description: Full extended model catalog.
content:
application/json:
schema:
"$ref": "#/components/schemas/ModelListResponse"
"/v1/models/search":
post:
tags:
- models
operationId: search
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/ModelSearchRequest"
responses:
'200':
description: Search results.
content:
application/json:
schema:
"$ref": "#/components/schemas/ModelSearchResponse"
"/v1/modalities":
get:
tags:
- modality
operationId: modality_list
x-speakeasy-name-override: list
responses:
'200':
description: Catalog of canonical modality groups, operations, model counts, and native pricing unit shapes.
content:
application/json:
schema:
"$ref": "#/components/schemas/ModalityListResponse"
"/v1/modalities/{modality}":
get:
tags:
- modality
operationId: modality_get
x-speakeasy-name-override: get
parameters:
- "$ref": "#/components/parameters/ModalityPath"
responses:
'200':
description: Catalog entry for one canonical modality.
content:
application/json:
schema:
"$ref": "#/components/schemas/ModalityCatalogEntry"
'400':
"$ref": "#/components/responses/ErrorResponse"
"/v1/modalities/{modality}/operations":
get:
tags:
- modality
operationId: operations_list
parameters:
- "$ref": "#/components/parameters/ModalityPath"
responses:
'200':
description: Operations available for one canonical modality.
content:
application/json:
schema:
"$ref": "#/components/schemas/OperationListResponse"
'400':
"$ref": "#/components/responses/ErrorResponse"
"/v1/modalities/{modality}/operations/{operation}/models":
get:
tags:
- modality
operationId: operation_models_list
parameters:
- "$ref": "#/components/parameters/ModalityPath"
- "$ref": "#/components/parameters/OperationPath"
- name: q
in: query
required: false
schema:
type: string
- "$ref": "#/components/parameters/ProviderQuery"
- name: streaming
in: query
required: false
schema:
type: boolean
- name: cursor
in: query
required: false
schema:
type:
- string
- 'null'
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
responses:
'200':
description: Cursor-paginated models that expose the requested canonical modality operation.
content:
application/json:
schema:
"$ref": "#/components/schemas/OperationModelsResponse"
'400':
"$ref": "#/components/responses/ErrorResponse"
"/v1/models/{model}":
get:
tags:
- models
operationId: get
parameters:
- "$ref": "#/components/parameters/ModelPath"
- "$ref": "#/components/parameters/ProviderQuery"
responses:
'200':
description: Model card.
content:
application/json:
schema:
"$ref": "#/components/schemas/Model"
'404':
"$ref": "#/components/responses/ErrorResponse"
"/v1/models/{model}/params":
get:
tags:
- models
operationId: params_get
parameters:
- "$ref": "#/components/parameters/ModelPath"
- "$ref": "#/components/parameters/ProviderQuery"
responses:
'200':
description: Provider-specific generation parameters.
content:
application/json:
schema:
"$ref": "#/components/schemas/ModelParamsResponse"
"/v1/responses":
post:
tags:
- inference
operationId: responses_create
security:
- KeyAuth: []
- X402Payment: []
parameters:
- "$ref": "#/components/parameters/SessionUserAddressHeaderOptional"
- "$ref": "#/components/parameters/ChainIdHeaderOptional"
- "$ref": "#/components/parameters/X402MaxAmountWeiHeader"
- "$ref": "#/components/parameters/IdempotencyKeyHeader"
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/ResponsesCreateRequest"
responses:
'200':
description: Response object or SSE stream when `stream` is true.
headers:
X-Receipt:
"$ref": "#/components/headers/Receipt"
PAYMENT-RESPONSE:
"$ref": "#/components/headers/PaymentResponse"
content:
application/json:
schema:
"$ref": "#/components/schemas/ResponseObject"
text/event-stream:
schema:
"$ref": "#/components/schemas/ResponseEventStream"
'402':
"$ref": "#/components/responses/PaymentRequiredResponse"
"/v1/responses/{responseId}":
get:
tags:
- inference
operationId: responses_get
parameters:
- "$ref": "#/components/parameters/ResponseIdPath"
responses:
'200':
description: Stored response object.
content:
application/json:
schema:
"$ref": "#/components/schemas/ResponseObject"
'404':
"$ref": "#/components/responses/ErrorResponse"
"/v1/responses/{responseId}/input_items":
get:
tags:
- inference
operationId: responses_input_items_list
parameters:
- "$ref": "#/components/parameters/ResponseIdPath"
responses:
'200':
description: Stored input items.
content:
application/json:
schema:
type: object
required:
- object
- data
properties:
object:
const: list
data:
type: array
items:
type: object
additionalProperties: true
"/v1/responses/{responseId}/cancel":
post:
tags:
- inference
operationId: responses_cancel
parameters:
- "$ref": "#/components/parameters/ResponseIdPath"
responses:
'200':
description: Cancelled response object.
content:
application/json:
schema:
"$ref": "#/components/schemas/ResponseObject"
components:
securitySchemes:
KeyAuth:
type: http
scheme: bearer
bearerFormat: compose-key
description: "`Authorization: Bearer compose-<jwt>`."
X402Payment:
type: apiKey
in: header
name: PAYMENT-SIGNATURE
description: Base64-url x402 v2 `PaymentPayload`.
parameters:
SessionUserAddressHeaderOptional:
name: x-session-user-address
in: header
required: false
schema:
"$ref": "#/components/schemas/WalletAddress"
ChainIdHeaderOptional:
name: x-chain-id
in: header
required: false
schema:
type: integer
minimum: 1
X402MaxAmountWeiHeader:
name: x-x402-max-amount-wei
in: header
required: false
schema:
"$ref": "#/components/schemas/AtomicAmount"
IdempotencyKeyHeader:
name: x-idempotency-key
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 200
ProviderQuery:
name: provider
in: query
required: false
schema:
"$ref": "#/components/schemas/ModelProvider"
ModalityQuery:
name: modality
in: query
required: false
schema:
"$ref": "#/components/schemas/CanonicalModality"
ModalityPath:
name: modality
in: path
required: true
schema:
"$ref": "#/components/schemas/CanonicalModality"
OperationPath:
name: operation
in: path
required: true
schema:
type: string
pattern: "^[a-z0-9][a-z0-9-]*$"
minLength: 1
ModelPath:
name: model
in: path
required: true
schema:
type: string
minLength: 1
ResponseIdPath:
name: responseId
in: path
required: true
schema:
type: string
minLength: 1
headers:
PaymentRequired:
description: Base64-url encoded x402 v2 PaymentRequired object.
schema:
type: string
PaymentResponse:
description: Base64-url encoded x402 settlement response.
schema:
type: string
Receipt:
description: Base64-url encoded Compose receipt.
schema:
type: string
responses:
ErrorResponse:
description: Compose error response.
content:
application/json:
schema:
oneOf:
- "$ref": "#/components/schemas/ErrorEnvelope"
- "$ref": "#/components/schemas/LegacyError"
PaymentRequiredResponse:
description: x402 payment challenge.
headers:
PAYMENT-REQUIRED:
"$ref": "#/components/headers/PaymentRequired"
content:
application/json:
schema:
oneOf:
- "$ref": "#/components/schemas/PaymentRequired"
- "$ref": "#/components/schemas/ErrorEnvelope"
schemas:
AtomicAmount:
type: string
pattern: "^[0-9]+$"
description: Non-negative integer amount in USDC atomic units.
examples:
- '1000000'
WalletAddress:
type: string
pattern: "^0x[a-fA-F0-9]{40}$"
examples:
- '0x1111111111111111111111111111111111111111'
ChainNetwork:
type: string
pattern: "^eip155:[0-9]+$"
examples:
- eip155:43113
HealthResponse:
type: object
additionalProperties: true
properties:
status:
type: string
timestamp:
type: string
ErrorEnvelope:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
LegacyError:
type: object
additionalProperties: true
properties:
error:
type: string
code:
type: string
message:
type: string
PaymentRequirements:
type: object
required:
- scheme
- network
- amount
- asset
- payTo
- maxTimeoutSeconds
properties:
scheme:
type: string
enum:
- exact
- upto
network:
"$ref": "#/components/schemas/ChainNetwork"
amount:
"$ref": "#/components/schemas/AtomicAmount"
asset:
"$ref": "#/components/schemas/WalletAddress"
payTo:
"$ref": "#/components/schemas/WalletAddress"
maxTimeoutSeconds:
type: integer
minimum: 1
extra:
type:
- object
- 'null'
additionalProperties: true
PaymentRequired:
type: object
required:
- x402Version
- resource
- accepts
properties:
x402Version:
const: 2
error:
type: string
resource:
type: object
required:
- url
properties:
url:
type: string
format: uri
description:
type: string
mimeType:
type: string
accepts:
type: array
minItems: 1
items:
"$ref": "#/components/schemas/PaymentRequirements"
extensions:
type:
- object
- 'null'
additionalProperties: true
ModelProvider:
type: string
enum:
- gemini
- openai
- fireworks
- asicloud
- alibaba
- hugging face
- azure
- aiml
- vertex
- cloudflare
- deepgram
- elevenlabs
- cartesia
- roboflow
CanonicalModality:
type: string
enum:
- text
- image
- audio
- video
- embedding
- realtime
PricingUnit:
type: object
required:
- unitKey
- entries
- valueKeys
properties:
unitKey:
type: string
minLength: 1
unit:
type: string
header:
type: string
entries:
type: object
additionalProperties:
type: number
valueKeys:
type: array
items:
type: string
default:
type: boolean
ModelOperationCapability:
type: object
required:
- modality
- operation
- sourceTypes
- input
- output
- pricingUnits
- streamable
properties:
modality:
"$ref": "#/components/schemas/CanonicalModality"
operation:
type: string
minLength: 1
sourceTypes:
type: array
items:
type: string
input:
type: array
items:
type: string
output:
type: array
items:
type: string
pricingUnits:
type: array
items:
"$ref": "#/components/schemas/PricingUnit"
streamable:
type: boolean
OperationCatalogEntry:
type: object
required:
- operation
- modelCount
- sourceTypes
- pricingUnits
properties:
operation:
type: string
minLength: 1
modelCount:
type: integer
minimum: 0
sourceTypes:
type: array
items:
type: string
pricingUnits:
type: array
items:
"$ref": "#/components/schemas/PricingUnit"
ModalityCatalogEntry:
type: object
required:
- modality
- operations
- modelCount
- pricingUnits
properties:
modality:
"$ref": "#/components/schemas/CanonicalModality"
operations:
type: array
items:
"$ref": "#/components/schemas/OperationCatalogEntry"
modelCount:
type: integer
minimum: 0
pricingUnits:
type: array
items:
"$ref": "#/components/schemas/PricingUnit"
ModalityListResponse:
type: object
required:
- object
- data
properties:
object:
const: list
data:
type: array
items:
"$ref": "#/components/schemas/ModalityCatalogEntry"
OperationListResponse:
type: object
required:
- object
- data
properties:
object:
const: list
data:
type: array
items:
"$ref": "#/components/schemas/OperationCatalogEntry"
Model:
type: object
required:
- modelId
- provider
properties:
modelId:
type: string
upstreamModelId:
type: string
name:
type:
- string
- 'null'
provider:
"$ref": "#/components/schemas/ModelProvider"
family:
type: string
type:
oneOf:
- type: string
- type: array
items:
type: string
- type: 'null'
description:
type:
- string
- 'null'
input: {}
output: {}
contextWindow: {}
pricing: {}
maxOutputTokens:
type: integer
capabilities: {}
modelType: {}
sourceMetadata: {}
params: {}
operations:
type: array
items:
"$ref": "#/components/schemas/ModelOperationCapability"
ownedBy:
type: string
createdAt:
oneOf:
- type: string
- type: integer
available:
type: boolean
availableFrom:
type: array
items:
type: string
hfInferenceProvider:
type: string
hfProviderId:
type: string
ModelListResponse:
type: object
required:
- object
- data
properties:
object:
const: list
data:
type: array
items:
"$ref": "#/components/schemas/Model"
ModelSearchRequest:
type: object
properties:
q:
type: string
modality:
"$ref": "#/components/schemas/CanonicalModality"
operation:
type: string
pattern: "^[a-z0-9][a-z0-9-]*$"
provider:
"$ref": "#/components/schemas/ModelProvider"
priceMaxPerMTok:
type: number
contextWindowMin:
type: integer
streaming:
type: boolean
cursor:
type:
- string
- 'null'
limit:
type: integer
minimum: 1
maximum: 200
ModelSearchResponse:
type: object
required:
- object
- data
- total
- next_cursor
properties:
object:
const: list
data:
type: array
items:
"$ref": "#/components/schemas/Model"
total:
type: integer
next_cursor:
type:
- string
- 'null'
OperationModel:
allOf:
- "$ref": "#/components/schemas/Model"
- type: object
required:
- operations
properties:
operations:
type: array
items:
"$ref": "#/components/schemas/ModelOperationCapability"
OperationModelsResponse:
type: object
required:
- object
- data
- total
- next_cursor
properties:
object:
const: list
data:
type: array
items:
"$ref": "#/components/schemas/OperationModel"
total:
type: integer
minimum: 0
next_cursor:
type:
- string
- 'null'
ModelParamsResponse:
type: object
required:
- modelId
- params
- defaults
properties:
modelId:
type: string
type:
type:
- string
- 'null'
provider:
type:
- string
- 'null'
params:
type: object
additionalProperties:
type: object
additionalProperties: true
defaults:
type: object
additionalProperties: true
Attachment:
type: object
additionalProperties: true
properties:
type:
type: string
description: Advisory attachment kind. The SDK/server do not reject unsupported model combinations.
enum:
- image
- audio
- video
- pdf
- file
- text
- json
- url
url:
type: string
uri:
type: string
data:
type: string
description: Data URL, plain text content, or provider-ready encoded payload.
base64:
type: string
mimeType:
type: string
contentType:
type: string
name:
type: string
filename:
type: string
text:
type: string
content:
type: string
detail:
type: string
enum:
- auto
- low
- high
metadata:
type: object
additionalProperties: true
AttachmentInput:
oneOf:
- "$ref": "#/components/schemas/Attachment"
- type: string
Attachments:
type: array
items:
"$ref": "#/components/schemas/AttachmentInput"
ResponseFormat:
type: object
additionalProperties: true
properties:
type:
type: string
enum:
- text
- json_object
- json_schema
json_schema:
type: object
additionalProperties: true
StreamOptions:
type: object
additionalProperties: true
properties:
include_usage:
type: boolean
include_obfuscation:
type: boolean
ReasoningOptions:
type: object
additionalProperties: true
properties:
effort:
type: string
summary:
type: string
Message:
type: object
required:
- role
- content
additionalProperties: true
properties:
role:
type: string
enum:
- system
- developer
- user
- assistant
- tool
content:
oneOf:
- type: string
- type: 'null'
- type: array
items:
type: object
additionalProperties: true
name:
type: string
tool_call_id:
type: string
tool_calls:
type: array
items:
type: object
additionalProperties: true
ResponsesCreateRequest:
type: object
required:
- model
- input
additionalProperties: true
properties:
model:
type: string
input: {}
attachments:
"$ref": "#/components/schemas/Attachments"
attachment:
"$ref": "#/components/schemas/AttachmentInput"
stream:
type: boolean
modalities:
type: array
items:
type: string
enum:
- text
- image
- audio
- video
- embedding
instructions:
type: string
previous_response_id:
type: string
max_output_tokens:
type: integer
temperature:
type: number
tools:
type: array
items:
type: object
additionalProperties: true
tool_choice: {}
response_format:
"$ref": "#/components/schemas/ResponseFormat"
stream_options:
"$ref": "#/components/schemas/StreamOptions"
parallel_tool_calls:
type: boolean
metadata:
type: object
additionalProperties: true
service_tier:
type: string
store:
type: boolean
reasoning_effort:
type: string
reasoning:
"$ref": "#/components/schemas/ReasoningOptions"
include:
type: array
items:
type: string
prompt_cache_key:
type: string
prompt_cache_retention:
type: string
text:
type: object
additionalProperties: true
n:
type: integer
size:
type: string
quality:
type: string
image_url:
type: string
voice:
type: string
language:
type: string
speed:
type: number
duration:
type: number
aspect_ratio:
type: string
resolution:
type: string
ResponseObject:
type: object
required:
- id
- object
- created_at
- status
- model
- output
additionalProperties: true
properties:
id:
type: string
object:
const: response
created_at:
type: integer
status:
type: string
enum:
- completed
- in_progress
- failed
- cancelled
model:
type: string
output:
type: array
items:
type: object
additionalProperties: true
usage:
type: object
additionalProperties: true
error:
type: object
additionalProperties: true
previous_response_id:
type: string
job_id:
type: string
receipt:
"$ref": "#/components/schemas/ReceiptBody"
ResponseEventStream:
description: SSE frames for response creation, text deltas, reasoning deltas,
tool calls, image partials, typed output items for text/image/audio/video/embedding,
video status, completion, `receipt`, and `compose.error`.
type: string
ReceiptBody:
type: object
additionalProperties: true
properties:
subject:
type: string
line_items:
type: array
items:
"$ref": "#/components/schemas/ReceiptLineItem"
provider_amount_wei:
"$ref": "#/components/schemas/AtomicAmount"
platform_fee_wei:
"$ref": "#/components/schemas/AtomicAmount"
final_amount_wei:
"$ref": "#/components/schemas/AtomicAmount"
tx_hash:
type: string
network:
"$ref": "#/components/schemas/ChainNetwork"
settled_at:
type: integer
ReceiptLineItem:
type: object
required:
- key
- unit
- quantity
- amount_wei
additionalProperties: true
properties:
key:
type: string
unit:
type: string
quantity:
type: number
unit_price_usd:
type: number
amount_wei:
"$ref": "#/components/schemas/AtomicAmount"