接続のしかた

CloneAI for Agents につなぐ入口と、それぞれに必要なものです。いま使える入口は REST API だけです。

"images":[{"media_type":"image/jpeg","data_base64":"<standard base64 of original image bytes>"}]

入口ごとの状態と、必要な能力

CLI と手元の MCP は、配布を始めたら、配布物・版・確かめたホストと版の組み合わせをこのページに載せます。確かめていない組み合わせは「未確認」と書きます。

CLI（準備中）の予定

まだ配布していません。配布する最初の版（v1）で対応しない条件は次のとおりです。これらに当たる依頼は、CLI が送る前に断ります（REST の手順では、これまでどおり使えます）。

• from_job.result_secret（依頼の本文に秘密を含む引き継ぎ）
• 公開鍵なしの sealed（result_public_key の無い完全非公開。依頼者の公開鍵の方式だけを使います）
• Node 22 未満

Not supported in the first CLI release (v1): from_job.result_secret, sealed without a public key, Node below 22.

REST：最短の手順（bash）

# 1. API キー（cga_…）を環境変数に置く。コマンドの行・依頼の本文・ログに鍵を書かない（cga_… は自分のキーに置き換える）
export CLONEAI_API_KEY='cga_…'

# 2. 受付の状態を見る（認証なし。accepting_jobs が true なら受付中）
curl https://ai.cloneai.jp/api/v1/capabilities

# 3. 自分のエージェントの ID と利用枠を確かめる（API キーだけで読む。作用なし。送り直す前にも、同じエージェントかをここで確かめる）
curl https://ai.cloneai.jp/api/v1/agents/me -H "Authorization: Bearer $CLONEAI_API_KEY"

# 4. 依頼の本文をファイルに書く（送り直すときも、このファイルをそのまま使う）。cost_requirement は必須：見積りの受入条件だけで実行してよいなら estimate_only、実費の絶対上限の保証が要るなら actual_limit（保証できないので 422 で実行しない）。サーバは補わない。visibility：private は結果を API キーだけで取れる（一般には出さない）。sealed は平文の取得に手元の秘密（result_secret か依頼者の秘密鍵）が要る
cat > request.json <<'EOF'
{"target":{"population":"synthetic_panel","max_respondents":30},"questions":[{"type":"choice","text":"在宅勤務を週に何日まで認める制度が望ましいと思いますか。","options":["週0日","週1〜2日","週3〜4日","毎日でもよい"]}],"visibility":"private","cost_requirement":{"kind":"estimate_only"}}
EOF

# 5. この依頼の Idempotency-Key（UUID v4）を 1 回だけ作り、ファイルに残す（送り直すときに作り直さない。uuidgen が無ければ python3 -c 'import uuid;print(uuid.uuid4())'）
uuidgen > request.key

# 6. 受付（job_id がすぐ返る）。応答が届いたか分からないときは、同じ 2 つのファイルのまま送り直す（キーの記録がある間は二重に受け付けない）
curl -X POST https://ai.cloneai.jp/api/v1/surveys -H "Authorization: Bearer $CLONEAI_API_KEY" -H "Idempotency-Key: $(cat request.key)" \
  -H "Content-Type: application/json" --data-binary @request.json

# 7. 進み具合（最大 30 秒待って返す。終わっていなければ retry_after_seconds の後にもう一度）
curl https://ai.cloneai.jp/api/v1/jobs/job_… -H "Authorization: Bearer $CLONEAI_API_KEY" -H "Prefer: wait=30"

# 8. 要約とレポートの引渡し（briefで要約、reportは照合用JSON。md・csvを保存しホストの添付機能で利用者へ渡す。/guide#delivery）
curl "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=report" -H "Authorization: Bearer $CLONEAI_API_KEY"
curl "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=json" -H "Authorization: Bearer $CLONEAI_API_KEY"
curl "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=md" -H "Authorization: Bearer $CLONEAI_API_KEY" --output report.md
curl "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=csv" -H "Authorization: Bearer $CLONEAI_API_KEY" --output answers.csv

REST：最短の手順（PowerShell）

# 1. API キー（cga_…）を環境変数に置く（このシェルの中だけ。cga_… は自分のキーに置き換える）
$env:CLONEAI_API_KEY = 'cga_…'

# 2. 受付の状態を見る（認証なし）
curl.exe https://ai.cloneai.jp/api/v1/capabilities

# 3. 自分のエージェントの ID と利用枠を確かめる（API キーだけで読む。作用なし）
curl.exe https://ai.cloneai.jp/api/v1/agents/me -H "Authorization: Bearer $env:CLONEAI_API_KEY"

# 4. 依頼の本文をファイルに書く（UTF-8・BOM なし。送り直すときも、このファイルをそのまま使う）
[IO.File]::WriteAllText("$PWD\request.json", '{"target":{"population":"synthetic_panel","max_respondents":30},"questions":[{"type":"choice","text":"在宅勤務を週に何日まで認める制度が望ましいと思いますか。","options":["週0日","週1〜2日","週3〜4日","毎日でもよい"]}],"visibility":"private","cost_requirement":{"kind":"estimate_only"}}')

# 5. この依頼の Idempotency-Key（UUID v4）を 1 回だけ作り、ファイルに残す（送り直すときに作り直さない）
[IO.File]::WriteAllText("$PWD\request.key", [guid]::NewGuid().ToString())

# 6. 受付。応答が届いたか分からないときは、同じ 2 つのファイルのまま送り直す
curl.exe -X POST https://ai.cloneai.jp/api/v1/surveys -H "Authorization: Bearer $env:CLONEAI_API_KEY" -H "Idempotency-Key: $(Get-Content request.key)" -H "Content-Type: application/json" --data-binary '@request.json'

# 7. 進み具合（最大 30 秒待つ）
curl.exe https://ai.cloneai.jp/api/v1/jobs/job_… -H "Authorization: Bearer $env:CLONEAI_API_KEY" -H "Prefer: wait=30"

# 8. 要約とレポートの引渡し（briefで要約、reportは照合用JSON。md・csvを保存しホストの添付機能で利用者へ渡す。/guide#delivery）
curl.exe "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=report" -H "Authorization: Bearer $env:CLONEAI_API_KEY"
curl.exe "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=json" -H "Authorization: Bearer $env:CLONEAI_API_KEY"
curl.exe "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=md" -H "Authorization: Bearer $env:CLONEAI_API_KEY" --output report.md
curl.exe "https://ai.cloneai.jp/api/v1/jobs/job_…/result?format=csv" -H "Authorization: Bearer $env:CLONEAI_API_KEY" --output answers.csv

送り直しの決まり

• Idempotency-Key は、1 つの依頼につき 1 回だけ作ります（UUID。v4 を勧めます）。本文と一緒に残し、送り直すときはその 2 つをそのまま使います。送る行の中で UUID を作ると（$(uuidgen) など）、送り直すたびに別の依頼になり、二重に受け付けられます。
• 同じキー＋同じ本文の再送は、新しいジョブを作らず、200 で最初のジョブを返します（Idempotent-Replayed: true）。キーの記録は 24 時間保持します。同じ内容の依頼は、キーを変えても最初の受付から 24 時間は新しく受け付けません（別のキーには 200 で元のジョブ・Request-Deduplicated: true）。それを過ぎ、元のジョブが終わっていれば、新しい依頼として受け付けます。
• 契約に無い欄は 400 invalid_request（details.reason＝unknown_fields）です。details.suggestions を見て本文を書き直し、新しいキーで送ります（例：target.size → target.max_respondents）。
• 同じキーで違う本文を送ると 409 idempotency_key_conflict です。依頼の内容を変えたら、新しいキーにしてください。409 request_in_progress は、同じ依頼を処理中です（この409を受け取った後、計時してRetry-After秒待つ。計時できない場合はwait_urlの200完了後、同じキー・同じ本文で再送する）。409 duplicate_request_unavailable は、24 時間の中で元のジョブが使えないときです（ジョブは作りません）。
• 受付が断られたとき（409 を除く 4xx・5xx）は、そのキーの記録は残りません。同じキーで送り直すと、新しい依頼として扱います。
• 受付ができたら job_id を残し、その後は GET /api/v1/jobs/{job_id} で状態を読みます。受付をやり直しません。
• 登録・キーの発行・見積り・訪問の通知・取消・削除・公開の申請は、受付と同じ送り直しの決まりではありません。応答が届いたか分からないときは自動で送り直さず、次のとおり決めてください。
  • 登録とキーの発行は、送るたびに新しい運営主体・キーを作ります（登録は、登録の数の上限も使います）。キーの発行なら GET /api/v1/operators/me でキーの一覧を確かめます。登録の応答が届かなかったときは鍵を受け取れていないので、登録し直します（前の登録は使えないまま残ります）。
  • 見積り（POST /api/v1/surveys/preview）はジョブを作らず、preview_id を返すだけです。応答を失ったとき、その見積りを取り出す手段はありません。必要なら、1 日の見積りの回数（仮登録 10 回・確認済み 60 回）をもう 1 回使い、対象の説明文（target.description）があれば対象の変換の費用がもう一度かかることを承知で、見積りし直します。見積りが要らなければ、元の本文（preview_id ではなく依頼の本文）で受付できます。
  • 訪問の通知は、同じ日に送り直しても数え直しません（送り直してかまいません）。
  • 取消・削除・公開の申請は、GET /api/v1/jobs/{job_id} でジョブの状態を読んでから決めます。

対応していない条件

• GET しかできない環境・閲覧だけの環境からは、受付できません（説明と公開の数字は読めます）。
• キーを URL に入れる方式はありません。Authorization の見出しだけです。
• ブラウザで依頼を書いて送る画面はありません。
• キーを付けた要求では、転送（リダイレクト）を自動で追わない設定にしてください。転送の先へキーや依頼を送らないためです。送り先は https://ai.cloneai.jp/api/v1 だけです。

完全な仕様

• OpenAPI（/openapi.json）：いま使える操作だけ
• 機械向けの要約（/llms.txt）
• 利用説明（日本語）・英語・アンケートの入力・出力・流れ

In English

The REST API (https://ai.cloneai.jp/api/v1) is the only way in now. A CLI, a local MCP server (stdio) and a remote MCP endpoint (/mcp) are not available yet; when they are released, only verified host and version combinations will be listed here. To submit a survey: keep your API key in an environment variable, write the request body to a file, create one Idempotency-Key (UUID) for that request and save it, then POST with both. If you do not know whether a response arrived, resend the same key and the same file (no second job while the key record is kept, 24 hours). A preview (POST /api/v1/surveys/preview) creates no job and returns only a preview_id. If its response is lost, there is no way to fetch that preview again. If you need it, preview again, knowing that it uses another daily preview (sandbox 10, verified 60) and, with a target.description, another conversion cost. If you do not need a preview, submit the original request body (not a preview_id). Registration and key issuance create a new operator or key on every request, so do not resend them automatically. For cancel, delete and publication requests, read the job state first. The bash and PowerShell steps above use the same commands as /en.