Introduction

Moises GraphQL API is available for third-party applications to leverage our AI technologies programmatically.

GraphQL is a way of building and accessing APIs that allows for more flexibility and efficiency than traditional REST API endpoints.

Queries And Mutations

In GraphQL, there are only two types of operations you can perform: query or mutation.

While we use queries to fetch data, we use mutations to modify server-side data.

If queries are the GraphQL equivalent to GET in REST, mutations represent the state-changing methods (like DELETE, PUT and PATCH).

You can learn more about GraphQL queries and mutations here.

Using the API

You can submit queries or mutations to our GraphQL endpoint using an HTTP Post Request, shown in the examples below.

import requests
import json

api_key = '[INSERT API KEY]'
endpoint = "https://api.moises.ai/graphql"
headers = {"authorization": api_key}

query = """query {
  user {
    id
  }
}"""

r = requests.post(endpoint, json={"query": query}, headers=headers)
if r.status_code == 200:
    print(json.dumps(r.json(), indent=2))
else:
    raise Exception(f"Query failed to run with a {r.status_code}.")
The query variable should be a string containing the GraphQL query or mutation. In this example query, the server will return the property ID for the user.

Examples

Here you can find query and mutation examples for a typical use case to Upload a file, Create a task, and Get Task status.

Upload a file

Request an upload of a file. Use FILESYSTEM provider to receive a signed url and upload using a local file. Use URL provider to upload from any public available URL via http protocol. Input should be any string representing a file name when using a FILESYSTEM provider or a valid URL in case you use a URL provider.

Example Mutation

mutation {
    uploadFile(type: URL, input: "https://www.dropbox.com/s/36ikz7k8ftxfjyh/Etnia_Tudo_Se_Passou.mp3"){
    name
    tempLocation
    }
  }
This example uploads a file from a Dropbox public URL

Example Return

{
    "data": {
      "uploadFile": {
        "name": "EtniaTudoSePassou",
        "tempLocation": "96331657e4217664bc74c66ada88a287"
      }
    }
  }
Now that you uploaded a file to Moises servers, you can use the tempLocation to create a task using it.

Create a Task

Submit a new task to the system using a tempLocation generated from an upload operation. The fields Input and name could be any string.

The operations field should be an array of valid operations, with its name and the parameters. Check our sample app or playground to see all available operations names as well as its possible parameters.

Example Mutation

mutation {
    createTask(
      file: {
        provider: URL
        input: "Etnia_tudo_se_passou.mp3"
        tempLocation: "96331657e4217664bc74c66ada88a287"
        name: "EtniaTudoSePassou"
      }
      operations: [{
        name: SEPARATE_B,
        params:{
          type: "vocals-drums-bass-other"
          maxDuration: 5000
        }
      }]
    )
The SEPARATE_B operation represents our flagship source separation algorithm.

Example Return

{
    "data": {
      "createTask": "d8b706e0-d18e-4ac6-9d98-6d951af3d4a5"
    }
  }
The task is being processed and its ID is d8b706e0-d18e-4ac6-9d98-6d951af3d4a5

Get Task status

Get the status and result of a task.

Possible statuses are STARTED, QUEUED, COMPLETED or FAILED. If completed, a result object will provide the output files.

Example Query

query {
    task(id:"d8b706e0-d18e-4ac6-9d98-6d951af3d4a5"){
      operations{
        status
        result
      }
    }
  }

Example Return

{
    "data": {
      "task": {
        "operations": [
          {
            "status": "COMPLETED",
            "result": {
              "files": {
                "bass": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/bass.m4a",
                "drums": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/drums.m4a",
                "other": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/other.m4a",
                "vocals": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/vocals.m4a",
                "bassHighRes": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/bass.wav",
                "drumsHighRes": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/drums.wav",
                "otherHighRes": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/other.wav",
                "vocalsHighRes": "/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/vocals.wav"
              }
            }
          }
        ]
      }
    }
  }
When the task is completed, you can see the result for the requested operations.

To download a file, just append our download url to the path of the file, example:

https://api.moises.ai/v3/download/moises-production--tasks/operations/SEPARATE_B/fd165388-809c-4a67-9d11-24166fbc50a3/vocals.m4a

Next steps

Now you can check our sample app (higher level) or playground (lower level) to deep dive into all available operations.

You can also check a few more query examples, for various use cases:

query {
                  tasks(pagination:{
                    limit:10,
                    offset: 0
                  }){
                  file{
                    name
                  }
                  operations{
                    result
                    status
                  }
                }
              }
Several mutations and query examples