# Translation: Order a job, or get the offer: the price and the exact next call.

URL: https://services.dev/docs/examples/lingua/api/order_translation

## Translation: Order a job, or get the offer: the price and the exact next call.

`POST /jobs` · `order_translation`

Status: live

Translation: send a document and a language; get a document back. $49 per job, within 48 hours, charged on delivery. AI delivers every job.

### Parameters

- `service` string · required: The Service to order: "translation".
- `document` object · file · required
  - `document.url` string · uri · required
  - `document.name` string · required
- `to` string · language · required: a BCP 47 tag, such as fr-CA
- `max_usd` number: The most you will pay, in dollars. Missing or below the price, you get an offer instead of a job.
- `key` string: Any string you choose. Retrying with the same key returns the same job.
- `metadata` object: Your own keys, echoed on the job and its events.
- `test_clock` string: A test clock the job runs on: tc_….

### Returns

- 200 job: The same job, for a key already used.
- 202 job: The job, working.
- 400 error: BLOCKED: body_invalid, version_unknown. (not captured yet)
- 401 error: BLOCKED: key_missing, key_invalid. (not captured yet)
- 402 OFFER: OFFER: the price and the exact next call.
- 403 error: BLOCKED: not_live, act_refused, region_not_ratified, brand_unverified. (not captured yet)
- 404 error: EMPTY: not_found. (not captured yet)
- 409 error: BLOCKED: key_reused.
- 422 error: BLOCKED: input_invalid, policy_invalid.
- 500 error: BLOCKED: api_error. (not captured yet)

### CLI

```
$ npx services.dev translation document=document.pdf to=fr-CA service=translation
OFFER · $49 per job, within 48 hours, charged on delivery.
  next    npx services.dev translation document=document.pdf to=fr-CA --max 49

$ npx services.dev translation document=document.pdf to=fr-CA --max 49
job_7Hq2 · working · $49.00 held
```

### API

```
curl http://localhost:8787/jobs \
  -H 'content-type: application/json' \
  -d '{"service":"translation","document":{"url":"https://example.com/document.pdf","name":"document.pdf"},"to":"fr-CA","max_usd":49,"key":"any-string-you-choose"}'
```

### MCP

```
→ order_translation {document: document.pdf, to: "fr-CA", key: "lease-fr-CA"}
← OFFER · $49 per job, within 48 hours, charged on delivery.
  next: order_translation {document: document.pdf, to: "fr-CA", max_usd: 49, key: "lease-fr-CA"}
→ order_translation {document: document.pdf, to: "fr-CA", max_usd: 49, key: "lease-fr-CA"}
← job_7Hq2 · working · $49.00 held
```

### SDK

```
// A buyer that is software: it reads lingua's card, asks the price, orders when the price fits
// its budget, waits for delivery and accepts. Run it beside `npx services.dev dev`.
import { connect } from 'services.dev/agent'
import translation from './services/translation.ts'

const lingua = connect('http://localhost:8787', { budget: 100 })
const lease = { url: 'https://example.com/lease.pdf', name: 'lease.pdf' }

const job = await lingua.order(translation, { document: lease, to: 'fr-CA' })
if (!('done' in job)) throw new Error(job.type === 'OFFER' ? job.price.sentence : job.reason)

const done = await job.done()
if (done.status !== 'delivered') throw new Error(`${done.id} ${done.status}`)
console.log(`${done.id} · delivered · ${done.output.document.name}`)

await job.accept()
console.log(`${done.id} · accepted · spent $${lingua.spent} of $100`)
```

### 202 job

```json
{
  "id": "job_7Hq2",
  "object": "job",
  "created": "2026-10-25T14:00:02.000Z",
  "livemode": false,
  "simulated": true,
  "service": "translation",
  "input": {
    "document": {
      "url": "https://example.com/document.pdf",
      "name": "document.pdf"
    },
    "to": "fr-CA"
  },
  "metadata": {},
  "price": {
    "usd": 49,
    "approved": false,
    "max_usd": 49
  },
  "payment": {
    "status": "held",
    "amount_usd": 49
  },
  "human": "AI delivers every job.",
  "stage": null,
  "steps": [
    {
      "id": "stp_1",
      "object": "step",
      "step": "draft",
      "by": "ai",
      "status": "working"
    },
    {
      "id": "stp_2",
      "object": "step",
      "step": "review",
      "by": "ai",
      "review": "adversarial",
      "status": "pending"
    }
  ],
  "next": [
    {
      "do": "get",
      "arguments": {
        "id": "job_7Hq2"
      },
      "tool": "get_job",
      "http": "GET http://localhost:8787/jobs/job_7Hq2?wait=50"
    },
    {
      "do": "cancel",
      "arguments": {
        "id": "job_7Hq2"
      },
      "tool": "cancel_job",
      "http": "POST http://localhost:8787/jobs/job_7Hq2/cancel"
    }
  ],
  "status": "working"
}
```

### 200 job

```json
{
  "id": "job_7Hq2",
  "object": "job",
  "created": "2026-10-25T14:00:02.000Z",
  "livemode": false,
  "simulated": true,
  "service": "translation",
  "input": {
    "document": {
      "url": "https://example.com/document.pdf",
      "name": "document.pdf"
    },
    "to": "fr-CA"
  },
  "metadata": {},
  "price": {
    "usd": 49,
    "approved": false,
    "max_usd": 49
  },
  "payment": {
    "status": "charged",
    "amount_usd": 49
  },
  "human": "AI delivers every job.",
  "stage": "review",
  "steps": [
    {
      "id": "stp_1",
      "object": "step",
      "step": "draft",
      "by": "ai",
      "status": "committed",
      "hash": "sha256:21255a755ba4991ffd2799e8fdf39d0997678ced5a36fea9d9c8c10e8154bf7f"
    },
    {
      "id": "stp_2",
      "object": "step",
      "step": "review",
      "by": "ai",
      "review": "adversarial",
      "verdict": "pass",
      "status": "committed",
      "hash": "sha256:95851b48d6d0adf87f5c3d1210a3157976f66081111d2367176e5f8c92508cb2"
    }
  ],
  "next": [
    {
      "do": "accept",
      "arguments": {
        "id": "job_7Hq2"
      },
      "tool": "accept_job",
      "http": "POST http://localhost:8787/jobs/job_7Hq2/accept"
    },
    {
      "do": "send_back",
      "arguments": {
        "id": "job_7Hq2",
        "note": ""
      },
      "tool": "send_back_job",
      "http": "POST http://localhost:8787/jobs/job_7Hq2/send_back"
    }
  ],
  "status": "delivered",
  "output": {
    "document": {
      "url": "data:text/plain,Simulated%20Translation%3A%20document",
      "name": "document.fr-CA.pdf"
    }
  },
  "final_at": "2026-11-01T14:00:16.000Z"
}
```

### 402 OFFER

```json
{
  "type": "OFFER",
  "object": "offer",
  "service": "translation",
  "title": "Translation",
  "price": {
    "usd": 49,
    "sentence": "$49 per job, within 48 hours, charged on delivery."
  },
  "eta": "48h",
  "terms": "Charged on delivery. Cancel at $0 until it ships. Send it back with a note and the AI redoes it, or you pay $0. Final 7 days after delivery.",
  "next": {
    "do": "order",
    "service": "translation",
    "arguments": {
      "document": {
        "url": "https://example.com/document.pdf",
        "name": "document.pdf"
      },
      "to": "fr-CA",
      "max_usd": 49,
      "key": "lease-fr-CA",
      "service": "translation"
    },
    "tool": "order_job",
    "http": "POST http://localhost:8787/jobs {\"service\":\"translation\"}"
  },
  "simulated": true
}
```

### 422 input_invalid

```json
{
  "type": "BLOCKED",
  "category": "invalid_request",
  "code": "input_invalid",
  "reason": "Missing to.",
  "param": "to",
  "next": {
    "do": "order",
    "service": "translation",
    "arguments": {
      "document": {
        "url": "https://example.com/document.pdf",
        "name": "document.pdf"
      },
      "max_usd": 49,
      "key": "lease-fr-CA-short",
      "to": null,
      "service": "translation"
    },
    "fill": [
      "to"
    ],
    "tool": "order_job",
    "http": "POST http://localhost:8787/jobs {\"service\":\"translation\"}"
  },
  "doc_url": "http://localhost:8787/docs/errors/input_invalid",
  "request_id": "req_m8cwgn",
  "simulated": true
}
```

### 409 key_reused

```json
{
  "type": "BLOCKED",
  "category": "conflict",
  "code": "key_reused",
  "reason": "That key was already sent with a different body.",
  "param": "key",
  "next": {
    "do": "order",
    "service": "translation",
    "arguments": {
      "document": {
        "url": "https://example.com/document.pdf",
        "name": "document.pdf"
      },
      "to": "de",
      "max_usd": 49,
      "key": "order-e70b04b9",
      "service": "translation"
    },
    "tool": "order_job",
    "http": "POST http://localhost:8787/jobs {\"service\":\"translation\"}"
  },
  "doc_url": "http://localhost:8787/docs/errors/key_reused",
  "request_id": "req_64K8AU",
  "simulated": true
}
```