Introduction

Welcome to the Mergely API! You can use our API to access mergely API endpoints, which you can submit tasks, get task results, either individually or in bulk. When a job is completed, it will be submitted to the web hook you specified. The biz type of a job can be speech2text, pic2text, translate, etc. We have examples in Shell, Ruby, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Mergely uses API keys to allow access to the API. You can register a new Mergely API key at our developer portal.

Mergely expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {token-should-replace-with-yours}

You must replace {token-should-replace-with-yours}> with your personal API key.

Job definition

full definition

{ "uuid":"xxx-xxxx-xxxx-xxxx", "status":"finished",// (pending, running, finished, failed, killed) "input_param":{ "file": "http://some.com/some.file" }, "biz": "speech2text", "result":{ "text":"..." }, "web_hook":"http://some.com/some-callback", "web_hook":"{'code':200}", "model":"some-algo",//optional "model_version":"some-version"//optional "finished_at":"2023-12-08 07:10:19.06959163 +0000", "reported_at":"2023-12-08 07:10:19.06959163 +0000", "created_at":"2023-12-08 07:10:19.06959163 +0000", "updated_at":"2023-12-08 07:10:19.06959163 +0000", }

required fields when submit a job

{ "input_param":{ "file": "http://some.com/some.file" }, "biz": "speech2text" }

accept fields when report job result

{ "uuid":"xxx-xxxx-xxxx-xxxx", "result":{ "text":"..." }, "model":"some-algo",//optional "model_version":"some-version"//optional }

Submit new Jobs

Post job individually

require 'rest-client'

RestClient.post 'https://console.mergely.app/api/v3/job/submit',
  {
    input_param:{
      file:"http://example.com/example.mp3"
    },
    biz: "speech2text"
  }.to_json,
  headers:{
    content_type: :json,
    as: :json
  }

import requests

url = 'https://console.mergely.app/api/v3/job/submit'
headers = {
    'Authorization': 'Bearer {token-should-replace-with-yours}',
    'Content-Type': 'Application/json',
    'Accept': 'Application/json'
}
data = {
    "job": {
           "input_param":{
                "file":"https://some.example.com/some.mp3"
            },
            "biz":"speech2text"
    }
}

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

print(response.status_code)
print(response.text)

curl "https://console.mergely.app/api/v3/job/submit" \
  -H "Authorization: Bearer {token-should-replace-with-yours}"
  -H "Accept: Application/json" \
  -H "Content-Type: Application/json" \
-d '{
    "job":{
            "input_param":{
                "file":"https://some.example.com/some.mp3"
            },
            "biz":"speech2text"
        }
  }'

fetch("https://console.mergely.app/api/v3/job/submit",{
    method:"POST",
    headers:{
        "Authorization": "Bearer {token-should-replace-with-yours}",
        "Content-Type":"Application/json",
        "Accept": "Application/json"
    },
    body:JSON.stringify({
        job:
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some.mp3"
            }
        }
    })
}).then((resp)=>{ resp.json() }).then((data)=>{
    console.log(data)
})

This endpoint create new single job.

HTTP Request

POST https://console.mergely.app/api/v3/job/submit

Query Parameters

Parameter	required	Default	Description
job	true	not default value	the job structure.

The job object returned when created:

{ "input_param":{ "file":"https://some.example.com/some.mp3", }, "biz":"speech2text" }

Post jobs in buck

HTTP Request

POST https://console.mergely.app/api/v3/job/submit/batch

Post body

Please submit jobs data as raw-body. You need to bring content-type:application/json and accept:application/json in the request header. input_param['file'] and biz are required.

{ jobs:[ { "input_param":{ "biz":"speech2text", "file":"https://some.example.com/some-1.mp3" } }, { "input_param":{ "biz":"speech2text", "file":"https://some.example.com/some-2.mp3" } } ] }

payload =  {
   jobs: [
  { input_param:{file: 'http://all.oss.aliyuncs.com/1.zip'},biz:"speech2text" },
  { input_param:{file: 'http://all.oss.aliyuncs.com/2.zip'},biz:"speech2text" }]
}.to_json

RestClient.post 'https://console.mergely.app/api/v3/job/submit/batch',
         payload,
          {
            authorization: "Bearer #{@token}" ,
            content_type: :json,
            as: :json
        }

import requests

url = 'https://console.mergely.app/api/v3/job/submit/batch'
headers = {
    'Authorization': 'Bearer {token-should-replace-with-yours}',
    'Content-Type': 'Application/json',
    'Accept': 'Application/json'
}
data = {
    "jobs":[
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some.mp3"
            }
        },
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some-2.mp3"
            }
        }
    ]
}

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

print(response.status_code)
print(response.text)

curl "https://console.mergely.app/api/v3/job/submit/batch" \
  -H "Authorization: Bearer {token-should-replace-with-yours}" \
  -H "Accept: Application/json" \
  -H "Content-Type: Application/json" \
-d '{
    "jobs":[
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some.mp3"
            }
        },
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some-2.mp3"
            }
        }
    ]
}'

fetch("https://console.mergely.app/api/v3/job/submit/batch",{
    method:"POST",
    headers:{
        "Authorization": "Bearer {token-should-replace-with-yours}",
        "Content-Type":"Application/json",
        "Accept": "Application/json"
    },
    body:JSON.stringify({
        jobs:[
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some.mp3"
            }
        },
        {
            "input_param":{
                "biz":"speech2text",
                "file":"https://some.example.com/some-2.mp3"
            }
        }
    ]})
})

The above command returns JSON structured like this:

{
  "ok": true,
  "data":[{
    "uuid":"xxxx-xxx-xxx-xxxx",
    "status":"pending"
  },
  {
      "uuid":"xxxx-xxx-xxx-xxxx",
      "status":"pending"
  }
  ]
}

Retrieve jobs

Retrieve job

HTTP Request

GET https://console.mergely.app/api/v3/job/query?uuid={uuid}

Query parameter

paramter	required	description
uuid	false	uuid of the job

require 'rest-client'
RestClient.get 'https://console.mergely.app/api/v3/job/query?uuid=' + the_uuid,{
    authorization: "Bearer {token-should-replace-with-yours}",
   content_type: :json,
   as: :json
}

import requests
url = "https://console.mergely.app/api/v3/job/query?id={some_uuid}"
headers = {
    'Authorization': 'Bearer {token-should-replace-with-yours}',
    'Content-Type': 'Application/json',
    'Accept': 'Application/json'
}
response = requests.get(url,headers=headers)

fetch("https://console.mergely.app/api/v3/job/query?uuid={some_uuid}",{
    headers:{
        "Authorization": "Bearer {token-should-replace-with-yours}",
        "Content-Type":"Application/json",
        "Accept": "Application/json"
    }
}).then((res)=>{ return res.json()}).then((data)=>{
    console.log(data);
})

curl "https://console.mergely.app/api/v3/job/query?uuid={some_uuid}" \
-H "Authorization: Bearer {token-should-replace-with-yours}" \
-H "Accept: Application/json" \
-H "Content-Type: Application/json"

Retrieve jobs in buck

HTTP Request

Query parameters

parameter	required	example	description
status	false	no default value	jobs with which status you wanner retrieve
biz	false	no default value	jobs with which biz model you wanner retrieve
size	false	20	pagesize of query
page	false	0	page number(starts at 0)

require 'rest-client'
RestClient.get 'https://console.mergely.app/api/v3/job/batch/query?biz=speech2text&status=pending&size=200&page=3',{
    authorization: "Bearer {token-should-replace-with-yours}",
   content_type: :json,
   as: :json
}

import requests
url = "https://console.mergely.app/api/v3/job/batch/query?biz=speech2text&status=pending&size=200&page=3"
headers = {
    'Authorization': 'Bearer {token-should-replace-with-yours}',
    'Content-Type': 'Application/json',
    'Accept': 'Application/json'
}
response = requests.get(url,headers=headers)

fetch("https://console.mergely.app/api/v3/?job/batch/query?biz=speech2text&status=pending&size=200&page=3",{
    headers:{
        "Authorization": "Bearer {token-should-replace-with-yours}",
        "Content-Type":"Application/json",
        "Accept": "Application/json"
    }
}).then((res)=>{ return res.json()}).then((data)=>{
    console.log(data);
})

curl "https://console.mergely.app/api/v3/job/query/batch?biz=speech2text&status=pending&size=200&page=3" \
-H "Authorization: Bearer {token-should-replace-with-yours}" \
-H "Accept: Application/json" \
-H "Content-Type: Application/json"

Errors

The Mergely API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.