---
title: クライアントライブラリ
description: サーバー側から生成ジョブを送信し、状態と結果を取得するための接続方法を確認します。
canonical_url: https://orchestor.io/docs/creative/client
markdown_url: https://orchestor.io/docs/creative/client.md
contentType: reference
---

# クライアントライブラリ

Python の標準ライブラリと Node.js の `fetch` を使う接続例です。認証情報を安全に保管できるサーバー側で実行してください。追加のパッケージは不要です。

- **[Python](#python)**
  同期処理と asyncio からの呼び出しを確認します。

- **[Node.js・TypeScript](#nodejs-and-typescript)**
  fetch で送信し、状態と結果を取得します。

## Python

### インストール

Python 3.9 以上を使用します。

```bash
python3 --version
```

### 認証情報を設定する

```bash
export ORCHESTOR_API_KEY="YOUR_API_KEY"
```

### 送信して完了を待つ

同期の例を `creative_client.py` として保存します。HTTP エラーは `HTTPError`、通信障害は `URLError` として呼び出し元へ返します。自動再送は行いません。

### 同期

```python
import json
import os
import time
import uuid
from urllib.request import Request, urlopen
from urllib.parse import quote

BASE_URL = "https://api.orchestor.io"


def request(path, payload=None, key=None, timeout=30):
    headers = {"Authorization": f"Bearer {os.environ['ORCHESTOR_API_KEY']}"}
    data = None
    if payload is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(payload).encode()
    if key:
        headers["Idempotency-Key"] = key
    req = Request(BASE_URL + path, data=data, headers=headers)
    with urlopen(req, timeout=timeout) as response:
        return json.load(response)["data"]


def generate():
    key = str(uuid.uuid4())  # 受付が不明な場合の再送に備えて保存します。
    submitted = request("/v1/creative/image-router/generate", {
        "model": "gpt-image-2", "prompt": "海辺の空を飛ぶ赤い凧", "mode": "async",
    }, key=key)
    job_id = quote(submitted["job"]["id"], safe="")
    deadline = time.monotonic() + 600
    state = submitted
    while not state.get("terminal", False):
        delay = max(1, state.get("next_poll_after_seconds") or 2)
        if time.monotonic() + delay >= deadline:
            raise TimeoutError(f"待機時間を超えました。job={job_id}, key={key}")
        time.sleep(delay)
        state = request(f"/v1/creative/jobs/{job_id}/status",
                        timeout=max(0.001, min(30, deadline - time.monotonic())))
    if not state.get("result_ready"):
        raise RuntimeError(f"ジョブが成功せず終了しました: {state.get('status')}")
    return request(f"/v1/creative/jobs/{job_id}/result")["result"]


if __name__ == "__main__":
    print(generate()["artifacts"])
```

### 非同期

```python
import asyncio
from creative_client import generate


async def main():
    result = await asyncio.to_thread(generate)
    print(result["artifacts"])


asyncio.run(main())
```

ライフサイクルを個別に制御するときは、返されたジョブ ID を保存して[状態取得・取消](https://orchestor.io/docs/creative/concepts/requests.md)を行います。入力メディアは[ファイルのアップロード](https://orchestor.io/docs/creative/uploads.md)で準備します。

## Node.js and TypeScript

### インストール

Node.js 24 以上を使用します。

```bash
node --version
```

### 認証情報を設定する

```bash
export ORCHESTOR_API_KEY="YOUR_API_KEY"
```

### 送信して完了を待つ

次の例を `.mjs` ファイルに保存して実行します。HTTP エラーを呼び出し元へ返し、最大10分間ポーリングします。

```javascript
const baseURL = 'https://api.orchestor.io';
const headers = {
  Authorization: `Bearer ${process.env.ORCHESTOR_API_KEY}`,
  'Content-Type': 'application/json',
};
const idempotencyKey = crypto.randomUUID();
const maxPollTime = 600_000;

async function readData(response) {
  const body = await response.json();
  if (!response.ok) {
    const error = new Error(body.error?.message ?? `HTTP ${response.status}`);
    error.status = response.status;
    error.apiError = body.error;
    throw error;
  }
  return body.data;
}

const submitted = await readData(await fetch(
  `${baseURL}/v1/creative/image-router/generate`,
  {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify({
      model: 'gpt-image-2',
      prompt: '海辺の空を飛ぶ赤い凧',
      aspect_ratio: '1:1',
      mode: 'async',
    }),
    signal: AbortSignal.timeout(30_000),
  },
));

const jobId = encodeURIComponent(submitted.job.id);
const deadline = Date.now() + maxPollTime;
let state = submitted;
while (!state.terminal) {
  const delay = Math.max(1, state.next_poll_after_seconds ?? 2) * 1000;
  const remaining = deadline - Date.now();
  if (remaining <= delay) {
    throw new Error(`待機時間を超えました。job=${jobId}, key=${idempotencyKey}`);
  }
  await new Promise(resolve => setTimeout(resolve, delay));
  state = await readData(await fetch(
    `${baseURL}/v1/creative/jobs/${jobId}/status`,
    {
      headers,
      signal: AbortSignal.timeout(Math.max(1, Math.min(30_000, deadline - Date.now()))),
    },
  ));
}

if (state.next_action !== 'fetch_result' || !state.result_ready) {
  throw new Error(`ジョブが成功せず終了しました: ${state.status ?? state.job?.status}`);
}
const result = await readData(await fetch(
  `${baseURL}/v1/creative/jobs/${jobId}/result`,
  { headers, signal: AbortSignal.timeout(30_000) },
));
console.log(result.result.artifacts);
```

ブラウザーに API キーを渡さず、サーバー側で実行してください。

> **待機終了は取消ではありません**
> 
> クライアントがタイムアウトしてもジョブは継続します。ジョブ ID で状態確認を再開してください。受付結果が不明な場合は、同じ入力と冪等性キーで再送します。

## 連携方法を選ぶ

| 用途 | 方法 |
| --- | --- |
| スクリプト・プロトタイプ | 上記の送信・待機例を使用します。 |
| ワーカーで状態を個別に管理 | `mode: "async"` で送信し、ジョブ ID を永続化します。 |
| ジョブ ID を取得済み | `status`・`result`・`cancel` を呼び出します。 |
| 本番のイベント駆動処理 | `mode: "webhook"` と `webhook_url` を指定し、通知欠落時はポーリングします。 |

入力と応答の仕様は [API リファレンス](https://orchestor.io/docs/creative/rest-api.md)で確認してください。

## 関連ページ

- [よくある質問](https://orchestor.io/docs/creative/help/faq.md)
- [サポート](https://orchestor.io/docs/creative/help/support.md)
- [Webhook](https://orchestor.io/docs/creative/webhooks.md)
- [レート制限](https://orchestor.io/docs/creative/concepts/rate-limits.md)
- [冪等性キー](https://orchestor.io/docs/creative/concepts/idempotency.md)

---

[Documentation index](https://orchestor.io/docs/llms.txt)
