✨ Refine a prompt version | API Reference

curl -X POST http://localhost:8000/api/prompts/1/versions/1/refine \
     -H "Authorization: Token  <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "project_id": 42,
  "teacher_model_name": "GPT-4-Refiner",
  "teacher_model_provider_connection_id": 7
}'

{
  "previous_version": {
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": {
      "avatar": "https://example.com/avatars/jdoe.png",
      "id": 15,
      "username": "jdoe",
      "email": "jdoe@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "id": 101,
    "model_display_name": "GPT-3.5 Turbo",
    "prompt": "Translate the following English text to French:",
    "provider_model_id": "gpt-3.5-turbo",
    "score": "0.87",
    "title": "English to French Translation Prompt",
    "updated_at": "2024-01-15T09:30:00Z",
    "max_few_shot_examples": 5,
    "model_provider_connection": 3,
    "organization": 12,
    "parent_model": 2,
    "provider": "OpenAI"
  },
  "prompt": "Translate the following English text to French, ensuring idiomatic expressions are preserved:",
  "reasoning": "Refined to improve translation accuracy and maintain natural language flow.",
  "refinement_job_id": "refine-20240612-abc123",
  "refinement_status": "completed",
  "title": "Enhanced English to French Translation Prompt",
  "total_cost": "0.045"
}

<Card href="https://humansignal.com/goenterprise"> <img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/> <p style="margin-top: 10px; font-size: 14px;"> This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise) </p> </Card> Refine a prompt version using a teacher model and save the refined prompt as a new version.

curl -X POST http://localhost:8000/api/prompts/1/versions/1/refine \
     -H "Authorization: Token  <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "project_id": 42,
  "teacher_model_name": "GPT-4-Refiner",
  "teacher_model_provider_connection_id": 7
}'

{
  "previous_version": {
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": {
      "avatar": "https://example.com/avatars/jdoe.png",
      "id": 15,
      "username": "jdoe",
      "email": "jdoe@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "id": 101,
    "model_display_name": "GPT-3.5 Turbo",
    "prompt": "Translate the following English text to French:",
    "provider_model_id": "gpt-3.5-turbo",
    "score": "0.87",
    "title": "English to French Translation Prompt",
    "updated_at": "2024-01-15T09:30:00Z",
    "max_few_shot_examples": 5,
    "model_provider_connection": 3,
    "organization": 12,
    "parent_model": 2,
    "provider": "OpenAI"
  },
  "prompt": "Translate the following English text to French, ensuring idiomatic expressions are preserved:",
  "reasoning": "Refined to improve translation accuracy and maintain natural language flow.",
  "refinement_job_id": "refine-20240612-abc123",
  "refinement_status": "completed",
  "title": "Enhanced English to French Translation Prompt",
  "total_cost": "0.045"
}

This endpoint is not available in Label Studio Community Edition. Learn more about Label Studio Enterprise

Refine a prompt version using a teacher model and save the refined prompt as a new version.

Authentication

AuthorizationToken

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example: <br><pre><code class="language-bash">curl https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>

Path parameters

prompt_idintegerRequired

version_idintegerRequired

Query parameters

asyncbooleanOptional

Whether to run the refinement asynchronously

Request

This endpoint expects an object.

project_idintegerRequired

Project ID to target the refined prompt for

teacher_model_namestringRequired>=1 character

Name of the model to use to refine the prompt

teacher_model_provider_connection_idintegerRequired

Model Provider Connection ID to use to refine the prompt

Response

Refined prompt response

previous_versionobject or null

Previous version of the prompt

promptstring

The refined prompt text

reasoningstring or null

Reasoning behind the refinement

refinement_job_idstring or null

Unique identifier for the refinement job

refinement_statusstring or null

Status of the refinement job

titlestring or null

Title of the refined prompt

total_coststring or null

Total cost of the refinement job (in USD)

$	curl -X POST http://localhost:8000/api/prompts/1/versions/1/refine \
>	-H "Authorization: Token <api_key>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"project_id": 42,
>	"teacher_model_name": "GPT-4-Refiner",
>	"teacher_model_provider_connection_id": 7
>	}'

1	{
2	"previous_version": {
3	"created_at": "2024-01-15T09:30:00Z",
4	"created_by": {
5	"avatar": "https://example.com/avatars/jdoe.png",
6	"id": 15,
7	"username": "jdoe",
8	"email": "jdoe@example.com",
9	"first_name": "John",
10	"last_name": "Doe"
11	},
12	"id": 101,
13	"model_display_name": "GPT-3.5 Turbo",
14	"prompt": "Translate the following English text to French:",
15	"provider_model_id": "gpt-3.5-turbo",
16	"score": "0.87",
17	"title": "English to French Translation Prompt",
18	"updated_at": "2024-01-15T09:30:00Z",
19	"max_few_shot_examples": 5,
20	"model_provider_connection": 3,
21	"organization": 12,
22	"parent_model": 2,
23	"provider": "OpenAI"
24	},
25	"prompt": "Translate the following English text to French, ensuring idiomatic expressions are preserved:",
26	"reasoning": "Refined to improve translation accuracy and maintain natural language flow.",
27	"refinement_job_id": "refine-20240612-abc123",
28	"refinement_status": "completed",
29	"title": "Enhanced English to French Translation Prompt",
30	"total_cost": "0.045"
31	}