# ORA API

## Intro to ORA API

ORA API is an integral part of ORA's Resilient Model Services (RMS). See [supported models and pricing](#supported-models-and-pricing) of ORA API.

The ORA API serves as the gateway for developers to interact with RMS, providing a decentralized, verifiable, and resilient platform for AI computations.

Advantages of ORA API are the best support for the most AI models in crypto; competitive pricing and predictable onchain cost; verifiable AI inference service; OpenAI compatibility...

## Integrate with ORA API

### Getting Started

Before using the ORA API, developers need to:

* [**Obtain API Key**](https://rms.ora.io/): Register for an ORA API key through [developer portal](https://rms.ora.io/) for authenticating requests.

API Key format as: `{NETWORK}:{KEY}` (eg. `BASE:5FABC....`)

* **Set Up Environment**: Ensure you have Python installed if you're using the SDK, or a tool like cURL for direct API calls.

### More about ORA API Key Design

1. Smart Contract Management
   1. All API keys are managed directly on the smart contract. This includes both the generation and deletion processes of API keys.
2. API Key Structure
   1. We do not store your API keys. Instead, the API key is generated through signing a message from the smart contract. The API key has the following structure, which enables you to recover it within your local environment: \
      `{blockchain identifier}:{base58encoding(message:signature(message, privateKey))}`
   2. Here, the message is a `bytes32` data type within the smart contract.
3. Key Generation and Deletion Mechanisms
   1. Generating a new API key is analogous to creating a new address from a wallet mnemonic. By monotonically increasing the value of the message, you can obtain a new API key. As for API key deletion, it is achieved by disabling the key within the smart contract.

## Use ORA API

### Chat Completion

<mark style="color:green;">`POST`</mark> `https://api.ora.io/v1/chat/completions`

Generate text responses from ORA API AI models.

**Headers**

| Name          | Value                  |
| ------------- | ---------------------- |
| Content-Type  | `application/json`     |
| Authorization | `Bearer <ORA_API_KEY>` |

**Body**

| Name                       | Type   | Description                                              |
| -------------------------- | ------ | -------------------------------------------------------- |
| `model`                    | string | Name of AI model                                         |
| `messages`                 | array  | Content for AI model to process                          |
| `search_enabled`(optional) | bool   | Bool for enabling search function that accesses web data |

**Example Call in shell**

```shell
curl -X POST "https://api.ora.io/v1/chat/completions" \
  -H "Authorization: Bearer $ORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V3",
    "messages": [{"role": "user", "content": "What are some fun things to do in New York?"}]
  }'
```

**Example Output**

```sh
{
  "object": "chat.completion",
  "model": "deepseek-reasoner",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The word \"strawberry\" is spelled as **S-T-R-A-W-B-E-R-R-Y**...",
        "reasoning_content": "Okay, so the user is asking..."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 1149,
    "total_tokens": 1164,
    "completion_tokens_details": {
      "reasoning_tokens": 1024
    }
  },
  "requestHash": "309904099dc718859f46bea07078214bff25b812440d7f12fcab5af98e10a4c5",
  "responseHash": "ecc1542ec60277e8e6a6ece5882b084a7f4ea71f5cc14b26471930814e1f8776"
}
```

#### Search Feature

For all chat completion models, you can use native search mode provided by ORA API.

In addition to the data without search, you get:

* inference result based on real-time searched content from web
* `search_result` that provides source that can be used as citation in inference result

```json
{
  "object": "chat.completion",
  "model": "deepseek-chat",
  // choices, usage, requestHash, responseHash
  "search_result": [
    {
      "url": "http://www.espn.com/nfl/superbowl/history/winners",
      "context": "View a comprehensive list of every single NFL Super Bowl champion from 1967 to present on ESPN. Includes the finals opponent, site of the game and the final ...",
      "source_from": "Google"
    },
    {
      "url": "https://blog.ticketmaster.com/super-bowl-winners/",
      "context": "The Kansas City Chiefs defeated the Philadelphia Eagles to win 38–35, led by a stellar performance from quarterback Patrick Mahomes.",
      "source_from": "Google"
    },
    {
      "url": "https://nflplayoffpass.com/super-bowl-winners/",
      "context": "Explore a comprehensive list of Super Bowl winners from 1967 to 2025, including the latest champions and Super Bowl LIX game results. ... Super Bowl Year Winner Opposition Score Stadium; LIX: 2025: Philadelphia Eagles: Kansas City Chiefs: 40-22: Caesars Superdome: LVIII: 2024: Kansas City Chiefs: San Francisco 49ers:",
      "source_from": "DuckDuckGo"
    },
    {
      "url": "https://en.wikipedia.org/wiki/List_of_Super_Bowl_champions",
      "context": "The Packers defeated the Chiefs in the first AFL-NFL World Championship Game (Super Bowl I).. The Super Bowl is the annual American football game that determines the champion of the National Football League (NFL). The game culminates a season that begins in the previous calendar year, and is the conclusion of the NFL playoffs.The winner receives the Vince Lombardi Trophy.",
      "source_from": "DuckDuckGo"
    }
  ],
}
```

For customized search enabled feature, you can choose to use other search providers ([example](https://community.openai.com/t/how-can-i-use-the-search-api/1003091/2)) without ORA API's native search, with recommended search prompt ([example](https://github.com/deepseek-ai/DeepSeek-R1#official-prompts)).

### Image Generation

<mark style="color:green;">`POST`</mark> `https://api.ora.io/v1/images/generations`

Generate images based on text prompts.

**Headers**

| Name          | Value                  |
| ------------- | ---------------------- |
| Content-Type  | `application/json`     |
| Authorization | `Bearer <ORA_API_KEY>` |

**Body**

| Name     | Type    | Description                                                    |
| -------- | ------- | -------------------------------------------------------------- |
| `model`  | string  | Name of AI model                                               |
| `prompt` | string  | Prompt for AI model to process                                 |
| `steps`  | integer | Number of diffusion steps AI model will take during generation |
| `n`      | integer | number of images to generate based on prompt                   |

**Example Call in shell**

```shell
curl -X POST "https://api.ora.io/v1/images/generations" \
  -H "Authorization: Bearer $ORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/FLUX.1-dev",
    "prompt": "Cats eating popcorn",
    "steps": 10,
    "n": 4
  }'
```

**Example Output**

```sh
{
  "model": "black-forest-labs/FLUX.1-dev",
  "object": "list",
  "data": [
    {
      "index": 0,
      "url": "https://gateway.pinata.cloud/ipfs/QmQBv5cDB12fsYuwYC6VNHL2o8hLEzs5XuPaCH1PT3s5qT"
    }
  ],
  "requestHash": "81112e1d9b3c7a547d5c5623218e5ceccc21ebe367b6ca096541f63664847056",
  "responseHash": "5eb34cd24096a77a2174ef870454fe47c6096c4d87a3d1559ab06c88624f4a94"
}
```

### Text to Video Generation

<mark style="color:green;">`POST`</mark> `https://api.ora.io/v1/videos/generations`

Generate videos based on text prompts.

<mark style="color:green;">`GET`</mark> `https://api.ora.io/v1/videos/result/$generation_id`

Get generated videos based on output id.

**Headers**

| Name          | Value                  |
| ------------- | ---------------------- |
| Content-Type  | `application/json`     |
| Authorization | `Bearer <ORA_API_KEY>` |

**Body**

| Name     | Type    | Description                         |
| -------- | ------- | ----------------------------------- |
| `model`  | string  | Name of AI model                    |
| `prompt` | string  | Prompt for AI model to process      |
| `seed`   | integer | Number for randomness in generation |

**Example in shell**

```shell
# POST - generate video
curl -X POST "https://api.ora.io/v1/videos/generations" \
  -H "Authorization: Bearer $ORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": ""KumoAnonymous/KumoVideo-Turbo",
    "prompt": "NYC Is A Great City",
    "seed": 0
  }'

# GET - get generation result
curl -X GET "https://api.ora.io/v1/videos/result/$generation_id" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $ORA_API_KEY"
```

**Example Output**

```json
// POST - generate video
{
  "task_id": "49aaa1dd-2c32-4bb3-a5b0-b2c887825b86",
  "hash_val": "6a042e860b658f973ab49b22ea565b4e19750fe7023ef23fcdef7b0960c63050",
  "status": "PROCESSING",
  "content": "",
  "requestHash": "82a1fa2d3edd3557ca2dddcfdef50dff5c9a19fa6c17bb2490aeee110b8b29d7",
  "responseHash": "d52de3784e1603d5977a5d522fafdefd3970bfd82b344bc59b54ee543502deb8"
}

// GET - get generation result
{
  "task_id": "1d73902d-cb58-4d4e-bb40-eb38bc13739a",
  "hash_val": "6a042e860b658f973ab49b22ea565b4e19750fe7023ef23fcdef7b0960c63050",
  "status": "OK",
  "video": "https://gateway.pinata.cloud/ipfs/QmUSZ3g5tQCYP38gukE73SFMKGEge2gNoVyDjXBiAKNqJy"
}
```

## SDK Integration

ORA API is designed to be compatible with the OpenAI SDK, facilitating a smooth transition for developers already familiar with it:

```python
import openai

# Define your query
system_content = "You are a helpful assistant."
user_content = "What are some fun things to do in New York?"

# Set your ORA API key
ORA_API_KEY = "YOUR_ORA_API_KEY"

# Initialize the client
client = openai.OpenAI(
    api_key=ORA_API_KEY,
    base_url="https://api.ora.io/v1",
)

# Perform a chat completion
chat_completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V3",
    messages=[
        {"role": "system", "content": system_content},
        {"role": "user", "content": user_content},
    ]
)

# Print the response
response = chat_completion.choices[0].message.content
print("Response:\n", response)
```

## Best Practices

* Error Handling: Always implement error handling to manage API response errors or timeouts.
* Rate Limiting: Be aware of and respect rate limits to avoid service disruptions.
* Security: Never expose your API key in client-side code. Use server-side calls or secure environment variables.