# Adding new Block via OpenAPI Spec ### Importing an Existing OpenAPI Specification 1. **Locate the API Specification**: Determine if the API specification exists at a known URL. For example, OpenAI's specification can be found at `https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml`. 2. **Validate the Specification**: Use `https://editor.swagger.io/` to validate the OpenAPI spec. 3. **Add to System**: * Navigate to `packages/omni-server/extensions/omni-core-blocks/server/apis/[NAMESPACE]/[NAMESPACE].yaml`. * Replace `[NAMESPACE]` with your desired namespace (e.g., `openai`). * Update the `api` section as below. #### Example Configuration for OpenAI ```yaml namespace: openai api: url: https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml basePath: https://api.openai.com/v1 componentType: OAIComponent31 ... ``` ### Creating an OpenAPI Spec 1. **Generate Draft Spec**: If the specification doesn't exist, use tools like "OpenAPI Spec Generator" or request ChatGPT 4 to draft an initial spec. 2. **Validate the Specification**: Use `https://editor.swagger.io/` to validate the OpenAPI spec. 3. **Add to System**: * Go to `packages/omni-server/extensions/omni-core-blocks/server/apis/[NAMESPACE]/api/[NAMESPACE].yaml`. * Replace `[NAMESPACE]` with your desired namespace (e.g., `getimg`). * Update the `api` section as below. #### Example Configuration for GetImg ```yaml namespace: getimg api: spec: ./api/getimg.yaml basePath: https://api.getimg.ai title: getimg ``` ### Configure API in YAML #### Patch Authentication We support the following authentication type: ``` http_basic' | 'http_bearer' | 'apiKey' | 'oauth2 ``` If auth is not defined globally in the original OpenAPI spec, you can patch it in the API yaml `/omni-core-blocks/server/apis/[NAMESPACE].yaml` ```yaml namespace: elevenlabs api: url: https://api.elevenlabs.io/openapi.json basePath: https://api.elevenlabs.io auth: type: apiKey requireKeys: - id: xi-api-key displayName: xi-api-key type: string in: header title: elevenlabs ``` #### Filter APIs ```yaml namespace: openai api: url: https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml basePath: https://api.openai.com/v1 componentType: OAIComponent31 auth: filter: operationIds: - createChatCompletion - createCompletion - createImage - createModeration - createTranscription - createTranslation - createImageVariation - createImageEdit - createEdit - listModels - createEmbedding title: openai ``` ### Configure Blocks in YAML #### Basic Metadata ```yaml category: Text-to-Speech description: >- Text to Speech Synthesis using the ElevenLabs API, supporting a variety of monolingual (english) and multilingual voices. meta: source: title: 'ElevenLabs: Text To Speech' links: Website: https://beta.elevenlabs.io/speech-synthesis Subscription: https://beta.elevenlabs.io/subscription API Reference: https://docs.elevenlabs.io/api-reference/quick-start/introduction Documentation: https://docs.elevenlabs.io/welcome/introduction Voice Lab: https://beta.elevenlabs.io/voice-lab summary: >- Text to Speech Synthesis using the ElevenLabs API, supporting a variety of monolingual (english) and multilingual voices. title: Text To Speech apiNamespace: elevenlabs apiOperationId: Text_to_speech_v1_text_to_speech__voice_id__post displayNamespace: elevenlabs displayOperationId: simpletts ``` #### Filter Inputs/Outputs ```yaml scripts: hideExcept:inputs: - prompt - temperature - model - top_p - seed - max_tokens - instruction - images hideExcept:outputs: - text ``` #### Transform ```yaml scripts: transform:inputs: transform:outputs: ``` #### Hoist? ```yaml scripts: hoist:input ``` #### Control ```yaml controls: preview: type: AlpineImageGalleryComponent displays: output:image opts: readonly: true ``` ```typescript placeholder? ``` #### Input type: customSocket: ```yaml image: customSocket: image ``` #### Socket Format Options Base64 image socket option: ```yaml socketOpts: format: base64 ``` ```yaml socketOpts: format: base64_withHeader ``` Array: ```yaml socketOpts: array: true ``` Allow multiple connect ```yaml allowMultiple: true ``` #### Rename ```yaml inputs: 'n': title: Number of Images ``` #### Run block to Generate Choices ```yaml model: type: string customSocket: text choices: block: getimg.listModels cache: global args: pipeline: face-fix family: enhancements map: title: name value: id ``` #### Use JSONATA to Manipulate the format 
messages:
    scripts:
      jsonata: >-
        [{"role":"system", "content": $string(instruction) }, {"role":"user",
        "content": $string(prompt) }]
      delete:
        - prompt
        - instruction
    hidden: true
#### Patch Security Scheme ```yaml securitySchemes ``` #### Default Result how to patch when response doesn't have property? ```yaml outputs: _omni_result: hidden: true ``` ### Special Cases When properties have mutually exclusive or dependencies ```yaml image_strength: scripts: jsonata: > $exists(init_image_mode) and init_image_mode = "IMAGE_STRENGTH" ? image_strength : undefined step_schedule_end: scripts: jsonata: > $exists(init_image_mode) and init_image_mode = "STEP_SCHEDULE" ? step_schedule_end : undefined step_schedule_start: scripts: jsonata: > $exists(init_image_mode) and init_image_mode = "STEP_SCHEDULE" ? step_schedule_start : undefined ``` Property name is Case-sensitive ```yaml Accept: hidden: true default: application/json Organization: hidden: true ``` When request content type is multipart/form-data, need file type to carry mimetype ``` image: customSocket: file ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://omnitool-ai.gitbook.io/omnitool/advanced/create-new-blocks/adding-new-block-via-openapi-spec.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.