Send your key
Put the key in theX-Moss-Provider-Key header. In the SDKs, pass it as api_key in Python or apiKey in JavaScript, and the SDK sends the header for you. These examples read an OpenAI key from OPENAI_API_KEY.
api_key to responses.create in Python. In JavaScript, pass apiKey in the second argument of responses.create. In JavaScript, a request field named apiKey or api_key throws, so keep the key out of the first argument.
Moss sends the key only to that vendor and never stores it. The SDKs send it as a header, never in the body. The reply’s model is the name you sent.
Which names work
With your key,model takes a listed id or the vendor’s own model name.
For example,
gpt-6-luna goes to OpenAI and claude-haiku-5-5 goes to Anthropic. Models lists the ids.
A vendor’s own name works only with your key. Without the key, the call returns 400 with code missing_provider_key.
Use the vendor’s own fields
The request reaches the vendor as you sent it, so it takes that vendor’s own fields. Moss does not hold it to the parameters refused on the Moss key. The vendor decides what it accepts. On your key, a prompt can hold up to 200,000 tokens. Errors and limits has the other limits.Handle vendor errors
A wrong or refused key gets the vendor’s own error and status. The error hastype model_error and code upstream_error. Its message starts with The model rejected the prompt, followed by the vendor’s message.
A bad key is 401 from OpenAI and Anthropic, and 400 from Google. Moss never retries the call on the Moss key, so fix the key and send the call again.
Know who bills what
Moss bills one retrieval for each request that searches your indexes, on any model. A call that names no index has no retrieval fee. Pricing has the details.