Skip to main content
POST
/
v1
/
evaluations
Submit an image for quality evaluation
curl --request POST \
  --url https://api.runflow.io/v1/evaluations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "generated_image_url": "<string>",
  "task_type": "<string>",
  "task_description": "<string>",
  "generation_prompt": "<string>",
  "evaluation_instructions": "<string>",
  "input_attributes": {},
  "reference_images": [
    {
      "url": "<string>",
      "kind": "<string>",
      "description": "<string>"
    }
  ],
  "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "client_ref": "<string>",
  "job_class": "standard",
  "callback_url": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "target_type_code": "<string>",
  "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "comfyui_workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "task_type": "<string>",
  "task_description": "<string>",
  "generation_prompt": "<string>",
  "generated_image_url": "<string>",
  "input_attributes": {},
  "evaluation_instructions": "<string>",
  "reference_images": [
    {}
  ],
  "overall_passed": true,
  "weighted_pass_rate": 123,
  "override_reason": "<string>",
  "top_issues": [
    "<string>"
  ],
  "top_strengths": [
    "<string>"
  ],
  "check_summary": {},
  "analysis_modules_executed": 123,
  "primary_action_code": "<string>",
  "parent_evaluation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "attempt_number": 123,
  "superseded_at": "2023-11-07T05:31:56Z",
  "eval_duration_ms": 123,
  "feedback_is_positive": true,
  "feedback_reason": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "client_ref": "<string>",
  "submitted_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "callback_url": "<string>",
  "cost": "<string>",
  "links": {},
  "judges": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "evaluation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "category": "<string>",
      "passed": true,
      "confidence": 123,
      "weight": 123,
      "reasoning": "<string>",
      "evidence": [
        "<string>"
      ],
      "sub_point_results": {},
      "sub_points_evaluated": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "issues": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "evaluation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "evaluation_judge_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "category": "<string>",
          "subcategory": "<string>",
          "detail": "<string>",
          "created_at": "2023-11-07T05:31:56Z"
        }
      ]
    }
  ],
  "gate_failures": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "evaluation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "output_key": "<string>",
      "module": "<string>",
      "reason": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "action": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "evaluation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "primary_action": "<string>",
    "failure_summary": "<string>",
    "improved_prompt": "<string>",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "run": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "comfyui_workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "target_version": "<string>",
    "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "input": {},
    "output": {},
    "context": {},
    "duration_ms": 123,
    "cost": "<string>",
    "cost_breakdown": {},
    "nodes_total": 123,
    "nodes_completed": 123,
    "resolved_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_ref": "<string>",
    "jurisdiction_code": "<string>",
    "flow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "request_id": "<string>",
    "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z",
    "callback_url": "<string>",
    "metadata": {},
    "has_logs": true,
    "has_node_runs": true,
    "links": {},
    "failure_code": "<string>",
    "failure_message": "<string>",
    "feedback_is_positive": true,
    "feedback_reason": "<string>",
    "source_chat_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "current_evaluation_summary": {
      "passed": true,
      "status_code": "<string>",
      "score": 0.5
    },
    "node_runs": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "node_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "state_code": "<string>",
        "input": {},
        "output": {},
        "input_signature": "<string>",
        "preview_type": "<string>",
        "preview_value": "<string>",
        "duration_ms": 123,
        "cost": "<string>",
        "retry_count": 123,
        "error_message": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "started_at": "2023-11-07T05:31:56Z",
        "completed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "logs": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "level_code": "<string>",
        "message": "<string>",
        "timestamp": "2023-11-07T05:31:56Z",
        "meta": {},
        "run": null
      }
    ],
    "model": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "model_creator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "slug": "<string>",
      "name": "<string>",
      "description": "<string>",
      "version": "<string>",
      "is_public": true,
      "is_open_source": true,
      "icon_url": "<string>",
      "cover_url": "<string>",
      "category_code": "<string>",
      "status_code": "<string>",
      "family_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "family_variant_code": "<string>",
      "param_count": "<string>",
      "architecture": "<string>",
      "license_code": "<string>",
      "max_resolution": "<string>",
      "lora_support": true,
      "fine_tuning": true,
      "supports_streaming": true,
      "paper_url": "<string>",
      "github_url": "<string>",
      "is_official": true,
      "availability_status": "<string>",
      "seo": {},
      "notable_features": [
        "<unknown>"
      ],
      "content": "<string>",
      "pricing_note": "<string>",
      "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z",
      "deleted_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "inputs": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "display_name": "<string>",
          "description": "<string>",
          "variable_type_code": "<string>",
          "default_behavior_code": "<string>",
          "validator_code": "<string>",
          "validator_attrs": {},
          "is_required": true,
          "default_value": {},
          "sort_order": 123,
          "is_featured": true,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "outputs": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "display_name": "<string>",
          "description": "<string>",
          "variable_type_code": "<string>",
          "validator_code": "<string>",
          "validator_attrs": {},
          "sort_order": 123,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "examples": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "title": "<string>",
          "description": "<string>",
          "input": {},
          "output": {},
          "status_code": 123,
          "cost": "<string>",
          "start_type": "<string>",
          "timing": {},
          "duration_ms": 123,
          "total_ms": 123,
          "thumbnail_url": "<string>",
          "category_code": "<string>",
          "is_featured": true,
          "is_public": true,
          "sort_order": 123,
          "ran_at": "2023-11-07T05:31:56Z",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "faq_entries": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "question": "<string>",
          "answer": "<string>",
          "sort_order": 123,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "pricing": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "pricing_model_code": "<string>",
          "rule_effect_code": "<string>",
          "model_input_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "match_value": null,
          "dimension_code": "<string>",
          "min_value": "<string>",
          "max_value": "<string>",
          "price": "<string>",
          "currency_code": "<string>",
          "unit_code": "<string>",
          "multiplier_label": "<string>",
          "description": "<string>",
          "sort_order": 123,
          "disabled_at": "2023-11-07T05:31:56Z",
          "measurement_source": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "related_links": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "related_model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "sort_order": 123,
          "created_at": "2023-11-07T05:31:56Z"
        }
      ]
    },
    "comfyui_workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "slug": "<string>",
      "name": "<string>",
      "description": "<string>",
      "workflow_json": {},
      "version": "<string>",
      "is_public": true,
      "status_code": "<string>",
      "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "environment": {},
      "models": {},
      "custom_nodes": {},
      "graph": {},
      "resources": {},
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z",
      "deleted_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "category_code": "<string>",
      "gpu_current_tier_code": "<string>",
      "inputs": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "comfyui_workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "display_name": "<string>",
          "description": "<string>",
          "variable_type_code": "<string>",
          "default_behavior_code": "<string>",
          "validator_code": "<string>",
          "validator_attrs": {},
          "is_required": true,
          "default_value": {},
          "sort_order": 123,
          "comfyui_node_id": "<string>",
          "comfyui_field_name": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "outputs": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "comfyui_workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "display_name": "<string>",
          "description": "<string>",
          "variable_type_code": "<string>",
          "validator_code": "<string>",
          "validator_attrs": {},
          "sort_order": 123,
          "comfyui_node_id": "<string>",
          "comfyui_field_name": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "gpu_explicit_models": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "comfyui_workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "gpu_model_code": "<string>",
          "created_at": "2023-11-07T05:31:56Z"
        }
      ]
    }
  },
  "model": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model_creator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "slug": "<string>",
    "name": "<string>",
    "description": "<string>",
    "version": "<string>",
    "is_public": true,
    "is_open_source": true,
    "icon_url": "<string>",
    "cover_url": "<string>",
    "category_code": "<string>",
    "status_code": "<string>",
    "family_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "family_variant_code": "<string>",
    "param_count": "<string>",
    "architecture": "<string>",
    "license_code": "<string>",
    "max_resolution": "<string>",
    "lora_support": true,
    "fine_tuning": true,
    "supports_streaming": true,
    "paper_url": "<string>",
    "github_url": "<string>",
    "is_official": true,
    "availability_status": "<string>",
    "seo": {},
    "notable_features": [
      "<unknown>"
    ],
    "content": "<string>",
    "pricing_note": "<string>",
    "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "deleted_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "inputs": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "display_name": "<string>",
        "description": "<string>",
        "variable_type_code": "<string>",
        "default_behavior_code": "<string>",
        "validator_code": "<string>",
        "validator_attrs": {},
        "is_required": true,
        "default_value": {},
        "sort_order": 123,
        "is_featured": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "outputs": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "display_name": "<string>",
        "description": "<string>",
        "variable_type_code": "<string>",
        "validator_code": "<string>",
        "validator_attrs": {},
        "sort_order": 123,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "examples": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "title": "<string>",
        "description": "<string>",
        "input": {},
        "output": {},
        "status_code": 123,
        "cost": "<string>",
        "start_type": "<string>",
        "timing": {},
        "duration_ms": 123,
        "total_ms": 123,
        "thumbnail_url": "<string>",
        "category_code": "<string>",
        "is_featured": true,
        "is_public": true,
        "sort_order": 123,
        "ran_at": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "faq_entries": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "question": "<string>",
        "answer": "<string>",
        "sort_order": 123,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "pricing": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "pricing_model_code": "<string>",
        "rule_effect_code": "<string>",
        "model_input_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "match_value": null,
        "dimension_code": "<string>",
        "min_value": "<string>",
        "max_value": "<string>",
        "price": "<string>",
        "currency_code": "<string>",
        "unit_code": "<string>",
        "multiplier_label": "<string>",
        "description": "<string>",
        "sort_order": 123,
        "disabled_at": "2023-11-07T05:31:56Z",
        "measurement_source": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "related_links": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "related_model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "sort_order": 123,
        "created_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "parent_evaluation": null
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Organization-Id
string | null

Body

application/json
​
generated_image_url
string
required

The image to evaluate: a public https:// URL, a runflow://assets/{uuid} reference from POST /v1/asset-uploads, or a data:image/... URI (materialized into a hosted asset).

Maximum string length: 12000000
​
task_type
string
required

What kind of generation produced the image, e.g. headshot or image_generation.

Required string length: 1 - 100
​
task_description
string | null

Longer description of the generation task, used to plan the evaluation.

Maximum string length: 4000
​
generation_prompt
string | null

The prompt that produced the image — strongly recommended for prompt-adherence judging.

Maximum string length: 10000
​
evaluation_instructions
string | null

Free-text rubric: what the evaluator should prioritize or ignore.

Maximum string length: 4000
​
input_attributes
Input Attributes · object

Structured generation attributes (e.g. {"style": "corporate"}) shown to the evaluator.

​
reference_images
EvaluationReferenceImage · object[] | null

Reference images for identity/garment comparison (max 4).

Maximum array length: 4
​
run_id
string<uuid> | null

Optional: associate this evaluation with one of your Runflow runs. The submitted image does not need to be the run's output (e.g. a post-processed export). Platform auto-evaluation of the run's own output is unaffected.

​
client_ref
string | null

Your correlation label, echoed in responses and callbacks. Not an idempotency key.

Maximum string length: 255
​
job_class
string
default:standard

Evaluation job class — see GET /v1/evaluations/job-classes for active classes and per-class prices. Currently only standard.

Maximum string length: 50
​
callback_url
string | null

HTTPS endpoint to receive a signed evaluation.completed / evaluation.failed callback when the evaluation terminates.

Maximum string length: 2048

Response

Successful Response

​
id
string<uuid> | null
​
org_id
string<uuid> | null
​
run_id
string<uuid> | null
​
target_type_code
string | null
​
model_id
string<uuid> | null
​
flow_id
string<uuid> | null
​
comfyui_workflow_id
string<uuid> | null
​
status_code
enum<string> | null
Available options:
pending,
running,
completed,
failed
​
task_type
string | null
​
task_description
string | null
​
generation_prompt
string | null
​
generated_image_url
string | null
​
input_attributes
Input Attributes · object
​
evaluation_instructions
string | null
​
reference_images
Reference Images · object[] | null
​
overall_passed
boolean | null
​
weighted_pass_rate
number | null
​
override_reason
string | null
​
top_issues
string[] | null
​
top_strengths
string[] | null
​
check_summary
Check Summary · object
​
analysis_modules_executed
integer | null
​
primary_action_code
string | null
​
parent_evaluation_id
string<uuid> | null
​
attempt_number
integer | null
​
superseded_at
string<date-time> | null
​
eval_duration_ms
integer | null
​
feedback_is_positive
boolean | null
​
feedback_reason
string | null
​
created_at
string<date-time> | null
​
updated_at
string<date-time> | null
​
source_code
enum<string> | null
Available options:
platform,
api
​
client_ref
string | null
​
submitted_at
string<date-time> | null
​
completed_at
string<date-time> | null
​
callback_url
string | null
​
cost
string | null
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
failure_code
enum<string> | null
Available options:
invalid_media,
dispatch_failed,
processing_failed,
timed_out
​
job_class_code
enum<string> | null
Available options:
standard,
quick
​
links
Links · object
​
judges
FullValidator · object[] | null
​
gate_failures
FullValidator · object[] | null
​
action
PublicValidator · object
​
run
FullValidator · object

Response shape.

​
model
FullValidator · object

Response shape.

​
parent_evaluation
unknown