{"openapi":"3.1.0","info":{"title":"Nicrron API","version":"1.0.0","description":"One OpenAI-compatible API for chat, embedding, audio, image and video models. Every path also answers under /api/v1. Docs: https://nicrron.ai/docs/api"},"servers":[{"url":"https://api.nicrron.ai/v1"}],"security":[{"bearer":[]}],"paths":{"/chat/completions":{"post":{"summary":"Create a chat completion","description":"OpenAI chat completions, plus `models` (fallbacks) and `provider` (routing). `model` may be a routing slug: nicrron/auto, nicrron/reasoning, nicrron/coding, nicrron/fastest, nicrron/cheapest. With temperature 0 or `x-nicrron-cache: true` the answer may come from a 24-hour cache scoped to your account.","parameters":[{"name":"x-nicrron-cache","in":"header","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"true caches this request; false never does."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"The completion, or a stream of chat.completion.chunk events when stream is true.","headers":{"x-request-id":{"schema":{"type":"string"}},"x-nicrron-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account suspended, or the key reached its spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached (see retry-after)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Every provider in the fallback chain failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/models":{"get":{"summary":"List models","description":"Every model with its context length and prices in US dollars per token. No key needed.","security":[],"responses":{"200":{"description":"The catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}}}}},"/embeddings":{"post":{"summary":"Create embeddings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"}}}},"responses":{"200":{"description":"OpenAI-format embedding list","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached (see retry-after)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Every provider in the fallback chain failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/speech":{"post":{"summary":"Text to speech","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudioSpeechRequest"}}}},"responses":{"200":{"description":"The audio file","content":{"audio/*":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; you were not charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/transcriptions":{"post":{"summary":"Speech to text","description":"Whisper. Files up to 26 MB.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string","default":"openai/whisper-1","description":"openai/whisper-1 or whisper-1"},"response_format":{"type":"string","enum":["json","text","verbose_json"],"default":"json"}}}}}},"responses":{"200":{"description":"The transcript","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; you were not charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/generations":{"post":{"summary":"Start a video job","description":"Charged upfront; refunded if the job fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationRequest"}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaJob"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; you were not charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/generations":{"post":{"summary":"Start an image job","description":"Charged upfront; refunded if the job fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaJob"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; you were not charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/generations/{id}":{"get":{"summary":"A video or image job's status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaJob"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/generations/{id}":{"get":{"summary":"An image job's status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaJob"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/generations/{id}/content":{"get":{"summary":"Download a finished video or image","description":"Kept for 30 days after the job finishes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The job has not finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The output expired and was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/generations/{id}/content":{"get":{"summary":"Download a finished image","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The job has not finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The output expired and was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generation":{"get":{"summary":"Look up one finished request","description":"Cost (fee included), tokens and timing, for your own requests. Can answer 404 for a moment while billing settles.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"The gen-… id (also the x-request-id header)"}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such model or job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key":{"get":{"summary":"The calling key","responses":{"200":{"description":"Label, lifetime spend, limits and balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Key"}}}},"401":{"description":"Missing, invalid or disabled key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A Nicrron API key, sk-af-…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"},"type":{"type":"string"}},"required":["message"]}}},"Message":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}}}}}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object"}}}},"ChatCompletionRequest":{"type":"object","required":["messages"],"description":"Fields not listed are passed on without checks.","properties":{"model":{"type":"string","maxLength":256,"description":"A model id or a routing slug."},"models":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Fallback models, tried in order after model."},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Message"}},"stream":{"type":"boolean"},"max_tokens":{"type":"integer","exclusiveMinimum":0},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"frequency_penalty":{"type":"number"},"presence_penalty":{"type":"number"},"seed":{"type":"integer"},"tools":{"type":"array","items":{"type":"object"}},"tool_choice":{},"response_format":{"type":"object"},"provider":{"type":"object","additionalProperties":false,"description":"Which providers may serve the request, and in what order.","properties":{"order":{"type":"array","items":{"type":"string"},"description":"Try these providers first, in this order."},"only":{"type":"array","items":{"type":"string"},"description":"Use only these providers."},"ignore":{"type":"array","items":{"type":"string"},"description":"Never use these providers."},"allow_fallbacks":{"type":"boolean","description":"false tries one endpoint per model."},"sort":{"type":"string","enum":["price","latency","throughput"]}}},"user":{"type":"string"}}},"ChatCompletion":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"chat.completion"},"created":{"type":"integer"},"model":{"type":"string","description":"The model that answered."},"provider":{"type":"string","description":"Who served it."},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/Message"},"finish_reason":{"type":"string"}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"cache_read_tokens":{"type":"integer"},"cache_write_tokens":{"type":"integer"}}}}},"EmbeddingRequest":{"type":"object","required":["input"],"properties":{"model":{"type":"string"},"models":{"type":"array","items":{"type":"string"}},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}},{"type":"array","items":{"type":"array","items":{"type":"number"}}}]},"encoding_format":{"type":"string","enum":["float","base64"]},"dimensions":{"type":"integer","exclusiveMinimum":0},"provider":{"type":"object","additionalProperties":false,"description":"Which providers may serve the request, and in what order.","properties":{"order":{"type":"array","items":{"type":"string"},"description":"Try these providers first, in this order."},"only":{"type":"array","items":{"type":"string"},"description":"Use only these providers."},"ignore":{"type":"array","items":{"type":"string"},"description":"Never use these providers."},"allow_fallbacks":{"type":"boolean","description":"false tries one endpoint per model."},"sort":{"type":"string","enum":["price","latency","throughput"]}}},"user":{"type":"string"}}},"AudioSpeechRequest":{"type":"object","additionalProperties":false,"required":["input"],"properties":{"model":{"type":"string"},"input":{"type":"string","minLength":1,"maxLength":4096},"voice":{"type":"string"},"response_format":{"type":"string","enum":["mp3","opus","aac","flac","wav","pcm"]},"speed":{"type":"number","minimum":0.25,"maximum":4}}},"VideoGenerationRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"model":{"type":"string"},"prompt":{"type":"string","minLength":1,"maxLength":4000},"aspect_ratio":{"type":"string","enum":["21:9","16:9","4:3","1:1","3:4","9:16"]},"resolution":{"type":"string","enum":["480p","720p","1080p"]},"duration":{"type":"integer","minimum":2,"maximum":30,"description":"Seconds; each model allows fewer values."},"generate_audio":{"type":"boolean","description":"Veo only; raises the price."},"camera_fixed":{"type":"boolean"},"seed":{"type":"integer"}}},"ImageGenerationRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"model":{"type":"string"},"prompt":{"type":"string","minLength":1,"maxLength":4000},"seed":{"type":"integer"}}},"MediaJob":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["video.generation","image.generation"]},"model":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","expired"]},"cost":{"type":"number","description":"US dollars, charged at submit."},"billing_units":{"description":"Returned on submit: what the cost was computed from."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"content_url":{"type":"string","description":"When succeeded."},"file_size":{"type":"integer","description":"When succeeded."},"error":{"type":"string","description":"When failed or expired."}}},"ModelList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"modality":{"type":"string"},"deprecated":{"type":"boolean"},"context_length":{"type":"integer"},"pricing":{"type":"object","properties":{"prompt":{"type":"string"},"completion":{"type":"string"}},"description":"US dollars per token, as strings."}}}}}},"Generation":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"provider_name":{"type":"string"},"tokens_prompt":{"type":"integer"},"tokens_completion":{"type":"integer"},"total_cost":{"type":"number"},"latency":{"type":"integer","description":"Milliseconds"},"time_to_first_token":{"type":["integer","null"],"description":"Milliseconds"},"streamed":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}},"Key":{"type":"object","properties":{"data":{"type":"object","properties":{"label":{"type":"string"},"usage":{"type":"number","description":"Lifetime spend in US dollars."},"limit":{"type":["number","null"],"description":"Spend limit in US dollars, or null."},"rate_limit":{"type":"object","properties":{"requests":{"type":"integer"},"interval":{"type":"string","const":"1m"}}},"balance":{"type":"number"}}}}}}}}