Venice.ai OpenAPI Specification v3.0.0

Production-ready OpenAPI definition for the Venice.ai API. This repository hosts the canonical spec used to generate SDKs, publish reference docs, and validate compatibility.

---

Table of Contents

• TL;DR
• What is This?
• Contents
• Quick Start
  • Validate in Browser
  • Local Validation
  • Local Preview with Swagger UI
• For Developers
  • Understanding the Structure
  • Making Changes
  • Contributing
• Generate SDKs
• Mock Server
• Differences from OpenAI's API
• Technical Specifications
• Usage Instructions
• Quality Metrics
• Additional Resources

---

TL;DR

• Spec lives in: venice.openapi.v3.yaml
• Lint and preview locally using the provided lint.sh script.
• Generate SDKs via openapi-generator
• Publish docs with your preferred pipeline (Swagger UI / Redoc)

---

What is This?

This repository contains the official OpenAPI 3.0.0 specification for the Venice.ai API. The specification serves as:

• 📚 Single Source of Truth: Canonical documentation for all API endpoints, parameters, and responses
• 🔧 SDK Generation: Input for generating client libraries in multiple programming languages
• 📖 Interactive Documentation: Source for Swagger UI, Redoc, and other API documentation tools
• ✅ Validation: Reference for validating API requests and responses
• 🤝 Integration Guide: Complete reference for developers integrating with Venice.ai

Key Benefits

• OpenAI Compatible: Drop-in replacement for OpenAI API clients
• Privacy Focused: Zero data retention - your data is never stored
• Comprehensive: Covers all Venice.ai API features including chat, images, audio, embeddings, and more
• Production Ready: Fully validated and tested specification
• Well Documented: Extensive examples, descriptions, and code samples

---

Contents

.
├─ venice.openapi.v3.yaml       # The complete OpenAPI specification
├─ .spectral.yaml               # Configuration for the Spectral linter
├─ lint.sh                      # Script to run local validation
├─ package.json                 # Node.js dependencies for linting
└─ README.md                    # This file

Quick Start

Validate in Browser (Zero Install)

1. Open editor.swagger.io
2. Import venice.openapi.v3.yaml
3. Confirm no errors; warnings are documented in comments where applicable.

Local Validation (Recommended)

A lint.sh script is provided to simplify local validation. It runs both Spectral and Redocly linters to ensure the OpenAPI specification is valid and adheres to style guidelines.

Prerequisites:

• Make sure npm is installed.
• Install the required Node.js dependencies:

  npm install

Usage: To run the linters, execute the script from the root of the repository:

./lint.sh

This will validate the venice.openapi.v3.yaml file and report any errors or warnings.

Local Preview with Swagger UI

# Option A: Serve with Docker (swaggerapi/swagger-ui)
docker run -p 8080:8080 -e SWAGGER_JSON=/tmp/spec.yaml   -v "$PWD/venice.openapi.v3.yaml":/tmp/spec.yaml swaggerapi/swagger-ui

# Option B: Redoc (static)
npx @redocly/cli build-docs venice.openapi.v3.yaml -o docs/index.html

Run Tests

The repository includes automated tests to validate the OpenAPI specification and code generation:

# Run comprehensive OpenAPI spec validation
python3 test_openapi_spec.py

# Run specific bug fix test (Preview tag)
python3 test_preview_tag_bug.py

# Run code sample generation tests
python3 test_add_code_samples.py

# Run code sample syntax validation tests
python3 test_code_sample_syntax.py

# Run edge case tests
python3 test_add_code_samples_edge_cases.py

# Run all tests
for test in test_*.py; do python3 "$test"; done

Test Coverage:

• ✅ File existence and YAML validity - Validates spec file structure
• ✅ OpenAPI version compliance - Ensures 3.0.0 compatibility
• ✅ Required sections - Validates info, servers, paths sections
• ✅ Security scheme definitions - Checks authentication setup
• ✅ Tag definitions and consistency - Ensures all tags are defined
• ✅ Component schema validation - Validates reusable schemas
• ✅ Code sample syntax - Verifies generated samples are valid
• ✅ Edge case handling - Tests error conditions and boundary cases
• ✅ Bug fixes - Regression tests for identified bugs

Test Statistics:

• Total Test Suites: 5
• Total Test Cases: 33
• Code Coverage: Comprehensive (all major functions tested)
• All Tests Passing: ✅ 100%

For Developers

Code Quality

This repository follows best practices for code quality and maintainability:

Documentation:

• ✅ All public functions have comprehensive Google-style docstrings
• ✅ Clear descriptions of parameters, return values, and side effects
• ✅ Usage examples included in docstrings
• ✅ Module-level documentation for each file

Testing:

• ✅ 33 comprehensive test cases covering all functionality
• ✅ Edge case and boundary condition testing
• ✅ Syntax validation for generated code samples
• ✅ Regression tests for identified bugs
• ✅ 100% test pass rate

Error Handling:

• ✅ Graceful handling of missing files and invalid YAML
• ✅ Proper encoding support (UTF-8)
• ✅ Validation of HTTP methods and path structures
• ✅ Informative error messages

Understanding the Structure

The OpenAPI specification is organized into several key sections:

1. Info Section (info)

Contains metadata about the API including title, version, description, and contact information.

2. Security (security, components.securitySchemes)

Defines authentication methods. Venice.ai uses Bearer token authentication with JWT format.

# In your requests:
Authorization: Bearer YOUR_API_KEY

3. Tags (tags)

Organizes endpoints into logical groups:

• Chat: Conversational AI endpoints
• Models: Model listing and information
• Image: Image generation and manipulation
• Characters: Custom AI personas
• API Keys: Key management
• Embeddings: Text embeddings
• Audio/Speech: Text-to-speech
• Billing: Usage tracking

4. Components (components.schemas)

Reusable schema definitions for requests and responses. These are referenced throughout the spec using $ref.

5. Paths (paths)

The actual API endpoints with their:

• Operations: GET, POST, DELETE, etc.
• Parameters: Query, path, and header parameters
• Request Bodies: Expected input schemas
• Responses: Possible response codes and schemas
• Examples: Request and response examples
• Code Samples: Usage examples in multiple languages

Making Changes

When modifying the specification:

1. Edit venice.openapi.v3.yaml directly
2. Follow OpenAPI 3.0.0 standards - refer to OpenAPI Specification
3. Validate frequently - run ./lint.sh after each change
4. Test your changes - preview in Swagger UI or Redoc
5. Check examples - ensure all examples are valid and realistic

Common Tasks

Adding a new endpoint:

paths:
  /your/new/endpoint:
    post:
      summary: Brief description
      description: Detailed explanation
      tags:
        - YourTag
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YourSchema'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YourResponseSchema'

Adding a new schema:

components:
  schemas:
    YourSchema:
      type: object
      properties:
        field_name:
          type: string
          description: What this field represents
          example: "example value"
      required:
        - field_name

Adding code samples:

x-codeSamples:
  - lang: 'Python'
    label: 'Basic Example'
    source: |
      import requests
      
      response = requests.post(
          'https://api.venice.ai/api/v1/your/endpoint',
          headers={'Authorization': 'Bearer {VENICE_API_KEY}'},
          json={'field': 'value'}
      )

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up your development environment
• Testing changes
• Submitting pull requests
• Code style and documentation standards

Quick contribution checklist:

• Fork the repository
• Create a feature branch
• Make your changes
• Run ./lint.sh to validate
• Test in Swagger UI or Redoc
• Submit a pull request with clear description

Generate SDKs

Using openapi-generator (Java-based tool):

# Install (one-time)
brew install openapi-generator   # macOS
# or: docker pull openapitools/openapi-generator-cli

# Typescript (fetch)
openapi-generator generate   -i venice.openapi.v3.yaml   -g typescript-fetch   -o sdk/typescript

# Python
openapi-generator generate   -i venice.openapi.v3.yaml   -g python   -o sdk/python

Notes:

• File upload endpoints are modeled with oneOf for binary (multipart), byte (base64 in JSON), and uri. Your generator should map these appropriately.
• Chat completion response role is restricted to assistant for OpenAI compatibility.

Mock Server (Optional)

docker run -p 4010:4010 -v "$PWD/venice.openapi.v3.yaml:/tmp/spec.yaml" stoplight/prism:4   mock -h 0.0.0.0 /tmp/spec.yaml

Differences from OpenAI's API

While Venice maintains high compatibility with the OpenAI API specification, there are some Venice-specific features and parameters:

1. venice_parameters: Venice offers additional configurations not available via OpenAI.
2. System Prompts: Different default behavior for system prompt handling.
3. Model Names: Venice provides transformation for some common OpenAI model selections to comparable Venice support models, although it is recommended to review the models available on Venice directly.

Venice-Specific Features

• Web Search Integration: Built-in web search with citations.
• Character Interactions: AI personalities and conversation styles.
• Reasoning Models: Advanced thinking and reasoning capabilities.
• Uncensored Responses: Default prompts designed for natural responses.

🔧 Technical Specifications

Validation Status

• OpenAPI 3.0.0 Compliant
• 0 Critical Errors
• 0 Warnings
• Ready for Production Use

Enhanced Features

1. Schema Quality

• Fixed nullable field handling across all schemas
• Improved type definitions with proper constraints
• Enhanced validation rules for request/response models
• Consistent schema structure throughout

2. Operation Documentation

• Summary & Description: Clear, feature-rich descriptions
• Parameters: Fully documented with examples and constraints
• Request Body: Comprehensive examples covering all major endpoints.
• Responses: Detailed success/error responses with headers
• Headers: Rate limiting, compression, request IDs

3. Code Samples

Comprehensive x-codeSamples covering:

cURL Examples:

curl -X POST "https://api.venice.ai/v1/chat/completions" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{
  "model": "venice-pro",
  "messages": [{"role": "user", "content": "Hello Venice"}]
}'

JavaScript Examples:

const response = await fetch("https://api.venice.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "venice-pro",
    messages: [{ role: "user", content: "Hello Venice" }]
  })
});

const data = await response.json();
console.log(data);

Python Examples:

import requests

url = "https://api.venice.ai/v1/chat/completions"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "model": "venice-pro",
    "messages": [{"role": "user", "content": "Hello Venice"}]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

4. Developer Experience

Tag Organization:

x-tagGroups:
  - name: Core AI Services
    tags: [Chat, Image, Audio, Speech, Embeddings]
  - name: Platform  
    tags: [Models, Characters, Billing, API Keys]
  - name: Experimental
    tags: [Preview]

Enhanced Documentation:

• Private AI guarantee prominently featured
• Zero-retention policy clearly explained
• Feature capabilities well documented
• Rate limiting and authentication details
• Comprehensive error handling guidance

Usage Instructions

For API Documentation Tools

1. Use venice.openapi.v3.yaml with Redoc, Swagger UI, or similar tools
2. The specification includes x-logo and styling information
3. Tag groups provide logical navigation structure

For Code Generation

• All schemas are properly defined for client generation
• Examples provide realistic integration patterns
• Error handling is comprehensively documented

For Developer Integration

• Copy code samples and replace {VENICE_API_KEY} with actual API key
• Examples demonstrate all major Venice features
• Authentication and error handling patterns included

Quality Metrics

Metric	Status	Details
Validation	✅	0 errors, 0 minor warnings
Coverage	✅	Complete /chat/completions documentation
Examples	✅	All endpoints have code samples
Error Handling	✅	All HTTP status codes documented
Authentication	✅	Bearer token with examples
Features	✅	Streaming, vision, tools, web search

Notes

• API Key Placeholder: All code samples use YOUR_API_KEY as a placeholder.
• Production Ready: Specification validates without errors
• Comprehensive Coverage: All major Venice features documented
• Best Practices: Follows OpenAPI 3.0.0 standards and conventions

Bug Fixes and Improvements

Recent Bug Fixes

Code Sample Syntax Errors (Fixed)

Issue: Generated code samples for POST/PUT/PATCH operations contained syntax errors:

• cURL samples missing line continuation backslash after Authorization header
• JavaScript samples missing comma after Authorization header in object literals

Impact: Users copying examples would encounter syntax errors when executing the code.

Fix: Updated add_code_samples.py to generate syntactically correct samples:

• ✅ cURL: Proper line continuation with backslashes
• ✅ JavaScript: Valid object literal syntax with commas
• ✅ Verified with comprehensive test suite (10 tests)

Test: Run python3 test_code_sample_syntax.py to verify the fix.

Details: See BUG_REPORT_CODE_SAMPLES.md for complete analysis.

Preview Tag Definition (Fixed)

Issue: The "Preview" tag was used in operation definitions but not defined in the global tags section.

Fix: Added Preview tag definition with appropriate description for beta/experimental endpoints.

Test: Run python3 test_preview_tag_bug.py to verify the fix.

Details: See BUG_REPORT_PREVIEW_TAG.md for complete analysis.

Additional Resources

Documentation

• Official API Docs: https://docs.venice.ai
• Venice.ai Platform: https://venice.ai
• OpenAPI Specification: https://spec.openapis.org/oas/v3.0.0

Tools

• Swagger Editor: https://editor.swagger.io - Online editor and validator
• Redocly CLI: https://redocly.com/docs/cli - Advanced linting and documentation
• Spectral: https://stoplight.io/open-source/spectral - OpenAPI linter
• OpenAPI Generator: https://openapi-generator.tech - SDK generation tool

Community & Support

• Discord Community: Join for support and updates
• GitHub Issues: Report bugs or request features
• Support Email: [email protected]

Related Files

• CONTRIBUTING.md - Contribution guidelines
• Venice.ai API reference KNOWLEDGE BASE.md - Comprehensive API knowledge base

API Version Information

• Current OpenAPI Version: 3.0.0
• API Version: 20250929.201934
• Last Updated: 2025-10-03

---

Maintained by: Fayeblade1488
License: MIT
Repository: venice-API-reference