Jobs methods

This describes the endpoints that deal with Jobs on the Gengo API.

Jobs (POST)

Summary :
Submits a job or group of jobs to translate. If all jobs which are placed in one order have same language pair and level then those jobs will be grouped.
URL :
http://api.gengo.com/v2/translate/jobs
Authentication :
Required
Parameters :
  • api_key (required) - Your API key
  • api_sig (required) - Your API signature
  • ts (required) - Current Unix epoch time as an integer
Data arguments :
  • jobs (required) - An array of Job Payloads. Please see the job payloads page for full details of the required parameters.

Example call

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
#!/usr/bin/python
# -*- coding: utf-8 -*-

from gengo import Gengo


gengo = Gengo(
    public_key='your_public_key',
    private_key='your_private_key',
    sandbox=False,
    debug=False)

data = {
    'jobs': {
        'job_1': {
            'type': 'text',
            'slug': 'Single :: English to Japanese',
            'body_src': 'Testing Gengo API library calls.',
            'lc_src': 'en',
            'lc_tgt': 'ja',
            'tier': 'standard',
            'auto_approve': 0,
            'comment': 'Instructions for translators on this specific job go here',
            'attachments': [{'url': 'http://example.com/image01.jpg', 'filename': 'image01.jpg', 'mime_type': 'image/jpg'},
                            {'url': 'http://example.com/video/1234', 'filename': 'video.mp4', 'mime_type': 'video/mp4'}],
            'callback_url': 'http://...',
            'custom_data': 'your optional custom data, limited to 1kb.',
            'force':  0,
            'use_preferred': 0,
        },
        'job_2': {
            'type': 'text',
            'slug': 'Single :: English to Japanese',
            'body_src': 'Testing Gengo API library calls.',
            'lc_src': 'en',
            'lc_tgt': 'ja',
            'tier': 'standard',
            'auto_approve': 0,
            'comment': 'Instructions for translators on this specific job go here',
            'attachments': [{'url': 'http://example.com/image02.jpg', 'filename': 'image02.jpg', 'mime_type': 'image/jpg'},
                            {'url': 'http://example.com/video/4321', 'filename': 'video01.mp4', 'mime_type': 'video/mp4'}],
            'callback_url': 'http://...',
            'custom_data':'your optional custom data, limited to 1kb.',
            'force':  0,
            'use_preferred': 0,
            'services': ['translation', 'edit'],
        },
    },
    'comment':'Instructions for translators on the entire order go here'
}

print(gengo.postTranslationJobs(jobs=data))

Comments

Please note that you can submit comments on individual jobs or on the entire order.

Response

In all cases, the response from should be near instant. That said, there are 3 possible types of response payloads depending on the jobs that were submitted in the POST call.

All jobs are new

If there are only new jobs, or all jobs have the force flag, the response will have a new order id, the number of jobs and the total cost of the order.

1
2
3
4
5
6
7
8
9
{
  "opstat": "ok",
  "response": {
    "job_count": 10,
    "order_id": 139370,
    "credits_used": 100.45,
    "currency": "USD"
  }
}

All jobs are old

If there are only 100% matching jobs (i.e. all jobs have already been ordered before and translations exist), the response is a list of the jobs, keyed the same as in the original submission. The status for these jobs will be updated as “approved”. Notice that each index is a list, as there may be several matching jobs for a single payload if the force flag has been used in past POSTs.

The translation is in the “body_tgt” variable. The order id will be new and the credits_used will be same amount, but not charged again because we have not ordered any new content.

  "opstat": "ok",
  "response": {
    "jobs": {
      "job_2": [
        {
          "custom_data": "1234567",
          "job_id": 1821444,
          "credits": 0.10,
          "auto_approve": 0,
          "eta": -1,
          "lc_tgt": "fr",
          "unit_count": 1,
          "lc_src": "en",
          "slug": "3",
          "callback_url": "http://example.com",
          "currency": "USD",
          "tier": "pro",
          "body_src": "Third",
          "body_tgt": "Troisieme",
          "ctime": 1378703629,
          "status": "reviewable"
        }
      ],
      "job_1": [
        {
          "custom_data": "1234567",
          "job_id": 1821443,
          "credits": 0.10,
          "auto_approve": 0,
          "eta": -1,
          "lc_tgt": "fr",
          "unit_count": 1,
          "lc_src": "en",
          "slug": "3",
          "callback_url": "http://example.com",
          "currency": "USD",
          "tier": "pro",
          "body_src": "Second",
          "body_tgt": "Deuxieme",
          "ctime": 1378703629,
          "status": "reviewable"
        }
      ]
    },
    "job_count": 2,
    "order_id": 754511,
    "credits_used": 0.00,
    "currency": "USD"
  }
}

There are repeated jobs in the jobs payload

If there are any jobs inside a payload that are repeats of any other jobs in the same payload, the response will return the same translated text of the previous jobs that were sent.

The job count will be the number of jobs sent, however the credits will only charge for one of the repeated jobs in the payload. A new order id is created for each request.

  "opstat": "ok",
  "response": {
    "jobs": [
      [
        {
          "job_id": 1087795,
          "credits": 0.10,
          "auto_approve": 0,
          "eta": 25308,
          "lc_tgt": "fr",
          "unit_count": 2,
          "lc_src": "en",
          "slug": "API Job test",
          "callback_url": "http://example.com",
          "currency": "USD",
          "tier": "standard",
          "body_src": "First test.",
          "body_tgt": "Premier test.",
          "ctime": 1378694499,
          "status": "available"
        }
      ],
      [
        {
          "job_id": 1087795,
          "credits": 0.10,
          "auto_approve": 0,
          "eta": 25308,
          "lc_tgt": "fr",
          "unit_count": 2,
          "lc_src": "en",
          "slug": "API Job test",
          "callback_url": "http://example.com",
          "currency": "USD",
          "tier": "standard",
          "body_src": "First test.",
          "body_tgt": "Premier test.",
          "ctime": 1378694499,
          "status": "available"
        }
      ]
    ],
    "job_count": 2,
    "order_id": 122900,
    "credits_used": 0.10,
    "currency": "USD"
  }
}

// Mix of new and old jobs
{

Mix of new and old jobs

If there is a mix of previously ordered jobs (100% matching in content and language pair) and new jobs in the POST, you will get back a response that contains the old jobs, an order ID for the new jobs and total cost for the new jobs in the order.

Please Note that the number of job_count will be the total number of jobs sent in your payload, not just the new ones.

    "jobs": {
      "old_job1": [
        {
          "custom_data": "1234567",
          "job_id": 1821444,
          "credits": 0.10,
          "auto_approve": 0,
          "eta": -1,
          "lc_tgt": "fr",
          "unit_count": 1,
          "lc_src": "en",
          "slug": "3",
          "callback_url": "http://example.com",
          "currency": "USD",
          "tier": "pro",
          "body_src": "Third",
          "body_tgt": "Troisieme",
          "ctime": 1378703629,
          "status": "reviewable"
        }
      ]
    },
    "job_count": 2,
    "order_id": 754513,
    "credits_used": 0.20,
    "currency": "USD"
  }
}

Jobs (GET)

Summary :
Retrieves a list of resources for the most recent jobs filtered by the given parameters.
URL :
http://api.gengo.com/v2/translate/jobs
Authentication :
Required
Parameters :
  • api_key (required) - Your API key
  • api_sig (required) - Your API signature
  • ts (required) - Current Unix epoch time as an integer
Data arguments :
  • status (optional) - “available”, “pending”, “reviewable”, “approved”, “rejected”, or “canceled”
  • timestamp_after (optional) - Epoch timestamp from which to filter submitted jobs
  • count (optional) - Defaults to 10 (maximum 200)
Note
  • If you only use count, you’ll get the most recent count jobs
  • If you use count with timestamp_after, you’ll get count jobs submitted since timestamp_after
  • If you only use timestamp_after, you’ll get all jobs submitted since timestamp_after

Example call

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#!/usr/bin/python
# -*- coding: utf-8 -*-

from gengo import Gengo


gengo = Gengo(
    public_key='your_public_key',
    private_key='your_private_key',
    sandbox=False,
    debug=False)

print(gengo.getTranslationJobs(status="available", count=15))

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "opstat": "ok",
  "response": [
    {
      "job_id": 123,
      "ctime": "..."
    },
    {
      "job_id": 425,
      "ctime": "..."
    },
    {
      "job_id": 274,
      "ctime": "..."
    }
  ]
}

Jobs by id (GET)

Summary :
Retrieves a list of jobs. They are requested by a comma-separated list of job ids.
URL :
http://api.gengo.com/v2/translate/jobs/{ids}
Authentication :
Required
Parameters :
  • api_key (required) - Your API key
  • api_sig (required) - Your API signature
  • ts (required) - Current Unix epoch time as an integer
Note
  • For the jobs that are file jobs, the response will include file_url_src and file_url_tgt

Example call

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#!/usr/bin/python
# -*- coding: utf-8 -*-

from gengo import Gengo


gengo = Gengo(
    public_key='your_public_key',
    private_key='your_private_key',
    sandbox=False,
    debug=False)

print(gengo.getTranslationJobBatch(id="1,2"))

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "opstat": "ok",
  "response": {
    "jobs": [
      {
        "custom_data": "{internal_id: 2311}",
        "job_id": 1,
        "credits": 0.25,
        "auto_approve": 1,
        "eta": 25308,
        "order_id": 54632,
        "lc_tgt": "jp",
        "unit_count": 5,
        "lc_src": "en",
        "slug": "This is a short story",
        "callback_url": "http://yourapp.com/gengo_callback/job/1",
        "currency": "USD",
        "tier": "standard",
        "body_src": "This is a short story",
        "ctime": 1352879655,
        "status": "available"
      },
      {
        "custom_data": "{internal_id: 2312}",
        "job_id": 2,
        "credits": 0.35,
        "auto_approve": 1,
        "eta": 25308,
        "order_id": 54632,
        "lc_tgt": "jp",
        "unit_count": 7,
        "lc_src": "en",
        "slug": "This is a short story as well",
        "callback_url": "http://yourapp.com/gengo_callback/job/2",
        "currency": "USD",
        "tier": "standard",
        "body_src": "This is a short story as well",
        "ctime": 1352879764,
        "status": "available"
      }
    ]
  }
}

Jobs (PUT)

Summary :
Updates a group of jobs to translate. Request should be no larger than 100MB. Comments per job should not exceed more than 25,000 characters.
URL :
http://api.gengo.com/v2/translate/jobs/
Authentication :
Required
Parameters :
  • api_key (required) - Your API key
  • api_sig (required) - Your API signature
  • ts (required) - Current Unix epoch time as an integer
Data arguments :
action (required): (per job) :
“revise“ - Returns this job back to the translator for revisions.

Other parameters

  • comment (required) - The reason to the translator for sending the job back for revisions.
“approve“ - Approves job.

Other parameters

  • rating (optional) 1 (poor) to 5 (fantastic)
  • for_translator (optional) - Comments for the translator
  • for_mygengo (optional) - Comments for Gengo staff (private)
  • public (optional) 1 (true) / 0 (false, default) - Whether Gengo can share this feedback publicly, including the source and target text (see Open Data).
“reject“ - Rejects the translation. Please see our FAQs for details of the rejection process.

Other parameters

  • reason (required) - “quality”, “incomplete”, “other”
  • comment (required)
  • follow_up (optional) “requeue” (default) or “cancel” - If you choose “requeue” the job will be rejected and then passed onto another translator. If you choose “cancel” the job will be completely cancelled upon rejection.

“archive“ - Archive approved job.

Example call

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
#!/usr/bin/python
# -*- coding: utf-8 -*-

from gengo import Gengo


gengo = Gengo(
    public_key='your_public_key',
    private_key='your_private_key',
    sandbox=False,
    debug=False)

# Archive a group of jobs
gengo.updateTranslationJobs(action={
    'job_ids': [4854, 547],
    'action': 'archive'
})

# Revise a group of jobs
gengo.updateTranslationJobs(action={
  'action': 'revise',
  'job_ids': [{'job_id': 922, 'comment': 'Please change the word banana to gorilla'},
            {'job_id': 923, 'comment': 'Please change the word banana to monkey'}],
})

## Reject a group of jobs
gengo.updateTranslationJobs(action={
  'action': 'reject',
  'job_ids': [{'job_id': 929, 'reason': 'quality', 'comment': 'This sentence should be in the past tense'},
              {'job_id': 811, 'reason': 'quality', 'comment': 'This should have be capitalized'}],
})

# Approve a group of jobs
gengo.updateTranslationJobs(action={
  'action': 'approve',
  'job_ids': [{'job_id': 924},
              {'job_id': 928}],
})

Response

// Archive a group of jobs
{
  "opstat": "ok",
  "response": {

  }
}

// Revising a group of jobs.
{
  "opstat": "ok",
  "response": {

  }
}

// Rejecting a group of jobs.
{
  "opstat": "ok",
  "response": {
    "jobs": [
      {
        "rejection_comments": "...",
        "worker_id": 4,
        "rejection_reason": "quality",
        "customer_id": 3,
        "job_id": 929
      },
      {
        "rejection_comments": "...",
        "worker_id": 4,
        "rejection_reason": "quality",
        "customer_id": 3,
        "job_id": 811
      }
    ]
  }
}

// Approving a group of jobs.
{
  "opstat": "ok",
  "response": {

  }
}