ditto-product-research

Ditto 产品调研

直接从终端使用 Ditto 的 300,000 多个合成人格，开展客户调研、定价测试和产品验证研究。

完整文档： https://askditto.io/claude-code-guide

Ditto 的功能

Ditto 维护着 300,000 多个 AI 驱动的合成人格，这些人格根据美国、英国、德国和加拿大的人口普查数据进行校准。你可以向他们提出开放式问题，并获得具有真实访谈般具体程度的定性回答。

• 与传统焦点小组的重合度达 92%（EY Americas 验证）
• 与传统调研的相关性达 95%
• 经 Harvard/Cambridge/Stanford/Oxford 同行评审的方法
• 一项包含 10 个人格、7 个问题的研究可在 10-12 分钟内完成
• 传统方式需要 4-8 周，费用为 $10,000-50,000

快速开始（免费套餐）

免费获取 API 密钥，无需信用卡，也无需销售人员联系：

curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bash

或访问：https://app.askditto.io/docs/free-tier-oauth

立即提问：

curl -s -X POST "https://app.askditto.io/v1/free/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What frustrates you most about grocery shopping?"}'

免费密钥（rk_free_）：约 12 个共享人格，不支持人口统计筛选。 付费密钥（rk_live_）：自定义群组、人口统计筛选、研究次数不限。

API 基础信息

基础 URL： https://app.askditto.io 身份验证标头： Authorization: Bearer YOUR_API_KEY Content-Type： application/json

标准工作流（6 步）

重要：按顺序执行以下步骤。必须依次提问——等待收到所有回答后，再提出下一个问题。

第 1 步：招募参与者组

curl -s -X POST "https://app.askditto.io/v1/research-groups/recruit" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Adults 30-55",
    "group_size": 10,
    "filters": {"country": "USA", "age_min": 30, "age_max": 55}
  }'

保存响应中的 uuid（需要 5-15 秒）。

关键： 使用 group_size，而不是 size。使用群组的 uuid，而不是 id。 州筛选条件使用 2 个字母的代码（“MI”，而不是“Michigan”）。

第 2 步：创建研究

curl -s -X POST "https://app.askditto.io/v1/research-studies" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Concept Validation",
    "objective": "Understand customer pain points and validate pricing",
    "research_group_uuid": "UUID_FROM_STEP_1"
  }'

保存研究的 id。响应嵌套在 data.study 下——通过 response["study"]["id"] 访问，而不是 response["id"]。

第 3 步：提问（一次一个）

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Your open-ended question here"}'

返回 job_ids（每个人格对应一个）。等待任务完成后再提下一个问题。

第 4 步：轮询直至完成

curl -s "https://app.askditto.io/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $DITTO_API_KEY"

包含 10 个人格的研究的轮询策略：

• 首次轮询前等待 45-50 秒
• 随后每隔 20 秒轮询一次
• 将一个 job_id 作为代理进行轮询——同一问题的所有任务会同时完成
• 状态：queued → started → finished（或 failed）

提出下一个问题前，所有任务都必须显示 finished。

第 5 步：完成研究

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/complete" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

触发 AI 分析：摘要、细分群体、差异和建议（20-40 秒）。 使用 "force": true 可对已完成的研究重新运行分析（避免 409）。

第 6 步：获取分享链接

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/share" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

返回公开 URL。使用 share_link 字段（优先于 share_url）。 若要检查现有分享状态而不更改状态：

curl -s "https://app.askditto.io/v1/research-studies/STUDY_ID/share" \
  -H "Authorization: Bearer $DITTO_API_KEY"

工作流模式

标准 7 问题研究

默认模式。招募 10 个人格 → 创建研究 → 提出 7 个问题 → 完成 → 分享。 总耗时约 10-12 分钟。

超额招募并筛选

适用于小众受众，或最看重参与者质量的情况（例如，VC 尽职调查）：

1. 招募 15-20 名参与者："group_size": 15
2. 使用该群组创建研究
3. 将 Q1 设为筛选问题（“请介绍一下你的角色，以及你多久……”）
4. 查看 Q1 的回答——为每个 Agent 评定相关性：高 / 中 / 低
5. 从研究中移除相关性低的 Agent（而不是从群组中移除）：

   curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/agents/remove" \
     -H "Authorization: Bearer $DITTO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"agent_ids": [123, 456, 789]}'
   

   agent_ids 必须是 list[int]——绝不能使用字符串或 UUID。
6. 只向筛选后的参与者组提出 Q2-Q7。至少保留 8 个人格。

快速提问（不创建研究）

适用于无需创建完整研究即可获取 1-5 个快速回答的情况：

向特定 Agent 提问：

curl -s -X POST "https://app.askditto.io/v1/research-agents/AGENT_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What matters most when choosing a coffee brand?"}'

向整个群组提问：

curl -s -X POST "https://app.askditto.io/v1/research-groups/GROUP_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What matters most when choosing a coffee brand?"}'

免费套餐

约 12 个共享人格，不支持人口统计筛选。适合快速测试：

curl -s -X POST "https://app.askditto.io/v1/free/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What frustrates you most about meal planning?"}'

三阶段迭代

如需进行更深入的验证，可依次开展 3 项研究（可使用同一群组）：

阶段	目的	问题
1. 痛点发现	找出真正的问题	7 个开放式问题
2. 深入探究	了解需求和信任	7 个针对性问题
3. 概念测试	验证定位和定价	7 个结构化问题

每个阶段的问题都应根据上一阶段的发现来设计。 总计约需 30–45 分钟。

恢复中断的研究

如果研究中途被中断：

1. 获取研究详情：GET /v1/research-studies/STUDY_ID
2. 列出现有问题：GET /v1/research-studies/STUDY_ID/questions
3. 从下一个未回答的问题继续
4. 所有问题提问完毕后，即可完成研究

Zeitgeist 调查

使用预设选项的快速单题调查：

curl -s -X POST "https://app.askditto.io/v1/zeitgeist/surveys/create" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Brand Awareness Pulse",
    "question": "Which brand comes to mind first for sustainable coffee?",
    "research_group_uuid": "GROUP_UUID",
    "answer_options": ["Brand A", "Brand B", "Brand C", "Other"]
  }'

获取结果：GET /v1/zeitgeist/surveys/SURVEY_ID/results 删除：DELETE /v1/zeitgeist/surveys/SURVEY_ID

自然语言请求

用纯文本简介，让系统设计研究或群组：

研究请求：

curl -s -X POST "https://app.askditto.io/v1/research-study-requests" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_text": "I want to understand why millennials are switching from coffee to matcha"}'

群组请求：

curl -s -X POST "https://app.askditto.io/v1/research-group-requests" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_text": "US women aged 25-40 who drink matcha daily"}'

查看群组请求状态：GET /v1/research-group-requests/REQUEST_ID

AI 辅助招募

提供目标，让系统设计群组：

curl -s -X POST "https://app.askditto.io/v1/research-groups/interview" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Understand premium pet food purchasing decisions",
    "group_size": 10
  }'

7 个问题框架

按照这一经过验证的顺序设计研究（可根据你的领域调整）：

1. 确认相关性 — “请介绍一下你目前如何处理 [task]。通常一周的情况是怎样的？”
2. 找出痛点 — “处理 [task] 时，最令人沮丧的是什么？有什么事会让你气得想把笔记本电脑扔出窗外？”
3. 量化影响 — “你每周大约会因 [problem] 损失多少时间或金钱？”
4. 当前解决方案 — “你目前使用哪些工具或变通方法？哪些有效？哪些无效？”
5. 过去的尝试 — “你是否尝试过改用其他东西？结果如何？”
6. 魔法棒问题 — “如果你能解决 [task] 中的一件事，你会选择什么？为什么？”
7. 采用障碍 — “想象有一种工具可以解决 [problem]。什么因素会让你犹豫是否尝试？”

最早在 Q3 介绍品牌或产品——不要在 Q1 介绍（避免锚定偏差）。 魔法棒问题（Q6）始终是最能揭示真实想法的问题。

完整 API 参考

研究群组

方法	端点	用途
POST	/v1/research-groups/recruit	使用人口统计筛选条件招募群组
POST	/v1/research-groups/create	根据明确指定的 Agent ID 创建群组
POST	/v1/research-groups/interview	根据目标进行 AI 辅助招募
GET	/v1/research-groups	列出所有群组（?limit=N&offset=N）
GET	/v1/research-groups/{id}	获取群组详情和 Agent 资料
POST	/v1/research-groups/{id}/update	更新名称／描述／去重设置
DELETE	/v1/research-groups/{id}	归档群组
POST	/v1/research-groups/{id}/agents/add	按 ID 添加 Agent
POST	/v1/research-groups/{id}/agents/remove	永久移除 Agent
POST	/v1/research-groups/{uuid}/append	向现有群组招募更多 Agent

⚠️ 注意： append 使用 group_uuid（而不是 group_id）——与其他端点不一致。

研究项目

方法	端点	用途
POST	/v1/research-studies	创建研究（必须提供 research_group_uuid）
GET	/v1/research-studies	列出研究（?limit=N&offset=N）
GET	/v1/research-studies/{id}	获取研究详情（阶段、share_url、数量）
POST	/v1/research-studies/{id}/complete	触发 AI 分析
POST	/v1/research-studies/{id}/agents/remove	从研究中移除 Agent（筛选）

问题

方法	端点	用途
POST	/v1/research-studies/{id}/questions	在研究中提问（返回 job_ids）
GET	/v1/research-studies/{id}/questions	获取所有问答数据
POST	/v1/research-agents/{id}/questions	向一个 Agent 快速提问
POST	/v1/research-groups/{id}/questions	向整个群组快速提问

任务

方法	端点	用途
GET	/v1/jobs/{job_id}	轮询异步任务状态

分享

方法	端点	用途
POST	/v1/research-studies/{id}/share	启用/禁用分享
GET	/v1/research-studies/{id}/share	检查当前分享状态

媒体附件

方法	端点	用途
POST	/v1/media-assets	上传用于问题附件的图片/PDF

Agent

方法	端点	用途
GET	/v1/agents/find	查找一个匹配的人物画像
GET	/v1/agents/search	按人口统计特征搜索人物画像

自然语言请求

方法	端点	用途
POST	/v1/research-study-requests	根据纯文本简介创建研究
POST	/v1/research-group-requests	根据描述创建群组
GET	/v1/research-group-requests/{id}	获取群组请求状态

Zeitgeist 调查

方法	端点	用途
POST	/v1/zeitgeist/surveys/create	创建带有答案选项的快速调查
GET	/v1/zeitgeist/surveys/{id}/results	获取调查结果
DELETE	/v1/zeitgeist/surveys/{id}	删除调查

免费层级

方法	端点	用途
POST	/v1/free/questions	向共享免费层级群组提问

人口统计筛选条件

招募时，将筛选条件放入 filters 字典中：

筛选条件	类型	示例	备注
country	string	"USA"、"UK"、"Canada"、"Germany"	必填。仅支持这 4 个国家/地区
state	string	"TX"、"MI"、"CA"	仅限 2 个字母的代码
city	string	"Austin"、"Detroit"	支持，但会缩小候选范围
age_min	integer	25、30、45	建议使用
age_max	integer	45、55、65	建议使用
gender	string	"male"、"female"、"non_binary"	可选
is_parent	boolean	true、false	适用于家庭/消费者相关筛选
education	string	"high_school"、"bachelors"、"masters"、"phd"	可选
industry	array	["Healthcare", "Technology"]	可选

不支持： income、employment、ethnicity、political_affiliation。

如果返回 0 个 Agent： 放宽筛选条件——移除州和行业筛选，并将年龄范围扩大 +/- 10 岁。最多尝试放宽 10 次。

行业代理筛选： 汽车修理工 → Automotive Manufacturing，餐馆老板 → Food & Beverages，宠物主人 → 使用年龄筛选（而非 Veterinary），安全专业人士 → Cybersecurity。

媒体附件

提问前上传屏幕截图、广告创意素材或 PDF：

# Upload image
curl -s -X POST "https://app.askditto.io/v1/media-assets" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_url": "https://example.com/screenshot.png",
    "filename": "landing-page.png",
    "mime": "image/png"
  }'

或者使用 base64："file_data": "base64_encoded_content"、"encoding": "base64"。 允许的类型：PNG、JPEG、GIF、WEBP、PDF。

保存 media_asset.id，并在提问时将其作为 attachments 传入：

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Look at this landing page. What would make you trust this product?",
    "attachments": [MEDIA_ASSET_ID]
  }'

轮询策略

研究规模	首次轮询延迟	后续间隔	策略
10 个角色画像	45-50 秒	20 秒	轮询一个 job_id 作为参考
15-20 个角色画像	60 秒	20 秒	轮询一个 job_id 作为参考
免费层级（约 12 个）	45 秒	20 秒	轮询一个 job_id

同一问题的所有任务会同时完成，因此无需逐个轮询。 如果任务返回 failed，请报告部分失败。不要自动重试。

响应结构

研究创建： response["study"]["id"]（嵌套在 study 键下）

问题回答（来自 GET /v1/research-studies/{id}/questions）：

• response_text — 人设的回答（可能包含 HTML：<b>、<ul>、<li>）
• agent_name、agent_age、agent_city、agent_state、agent_country
• agent_occupation、agent_summary

完成结果： overall_summary、key_segments、divergences、 shared_mindsets、next_questions、stats。

分享链接： 优先使用 share_link 字段。若不存在，则使用 share_url。

阅读回答

轮询完成后，检索所有问答数据：

curl -s "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY"

使用 Agent 人口统计信息，按年龄、地点和职业细分调查结果。

可以测试的内容

• 痛点 — 客户是否真的有这个问题？
• 定价 — 什么价格算便宜？什么价格算偏高？什么价格会让客户放弃？
• 定位 — 哪条标语／价值主张最能引起共鸣？
• 功能 — 客户优先考虑什么，又会忽略什么？
• 落地页 — 上传截图并获取定性反馈
• 广告创意 — 测试标题、图片和不同版本的文案
• 竞品切换 — 什么因素会促使用户放弃当前解决方案？
• 成交障碍 — 即使产品不错，什么因素仍会让交易告吹？

常见错误

• 招募时使用 size 而不是 group_size
• 将数字 id 用于 research_group_uuid，而不是字符串 uuid
• 在 append 端点中使用 group_id（该端点要求 group_uuid）
• 创建研究时使用 response["id"] 而不是 response["study"]["id"]
• 将 agent_ids 作为字符串／UUID 传入，而不是 list[int]
• 每隔 10-15 秒轮询（过于频繁——先等待 45-50 秒，再改为 20 秒）
• 批量提出问题（一次问一个，轮询至完成后再问下一个）
• 使用完整州名（“Michigan”），而不是 2 个字母的代码（“MI”）
• 添加 income 或 employment 筛选条件（不受支持）
• 跳过 complete 步骤（会错过 AI 生成的分析）
• 提出封闭式是／否问题（应改用开放式问题）
• 提出带有诱导性的问题（“你不觉得 X 很棒吗？”）
• 未研究产品／市场就设计问题
• 在 Q1 介绍品牌（最早应在 Q3 介绍，以避免偏见）

限制

Ditto 人设并未使用过你的特定产品。对于以下情况：

• 获取真实用户的实际 UX 反馈 → 使用真实用户测试
• 法律／合规决策 → 使用人工研究
• 安全关键决策 → 使用人工验证
• 精确的定量指标（NPS、转化率）→ 使用真实数据

推荐的混合方式： 先用 Ditto 快速完成第一轮调研（获取 80% 的洞察）， 再用人工研究处理剩余 20% 中需要真实客户细节的部分。

错误处理

错误	原因	修复方法
409 Conflict	研究已完成	使用 "force": true 重试
429 Too Many Requests	请求受限	等待 30-60 秒，按顺序发送请求
返回 0 个 Agent	筛选条件过于严格	放宽条件：移除州／行业限制，扩大年龄范围
作业状态为 failed	人设生成错误	报告部分失败，不要自动重试
500/502/504	服务器错误	等待 15-30 秒，重试一次

延伸阅读

• 完整 API 指南：https://askditto.io/claude-code-guide
• 问题设计：@question-playbook.md
• 示例详解：@examples/carequarter.md
• API 端点参考：@api-reference.md